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Hartley was also responsible for modifying the 940 LISP compiler to generate 
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C. Lewis, and L. M. Masinter. The cover was designed by Alice R. Fikes. 
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Stanford University, in addition to being available at Computer Corporation of 
America and Case Institute of Technology. The total INTERLISP-10 user 
community now comprises approximately one hundred users. Implementations of 
IMTERIXSP for the IBM 370, CDC 3300, and Burroughs 6700 are nearing 

completion. 



IMTERLISP is a continuously evolving system, both in response to complaints, 
suggestions, and requests of the many users scattered throughout the ARPA 
network, as well as the long range goals of the individuals primarily 
responsible for the system, which are currently: 



Person 
W. Teitelman 
Xerox Palo Alto 

Research Center 
3180 Porter Drive 
Palo Alto, Calif, 94304 



Responsible for 

User Facilities? i.e., pretty-print, editor, 
break and trace, advising, printstructure, 
DW1M, CUSP, programmer's assistant, etc. 



A. K. Hartley 
Bolt Beranek & Newman 
50 Houlton St. 
Cambridge, Mass. 02138 



IMTERLISP-iO interpreter, garbage collector, 

all SUBR J s(hand»code machine language functions), 

compiler. 



D. C. Lewis 
Bolt Beranek & Newman 
50 Houlton St. 
Cambridge, Mass. 02138 



1NTERUSP-10 input-output, readtables, 
terminal tables, user data types. 



J. W . Goodwin 
Bolt Beranek & Newman 
50 Houlton St. 
Cambridge, Mass. 02138 



INTERLISP-10 overlays, sysin, sysout, makesys, 
special arithmetic functions, functions 
for accessing TENEX capabilities, TRANSOR, 



L. M . Masinter 
Xerox Palo Alto 

Research Center 
3180 Porter Drive 
Palo Alto, Calif. 94304 



pattern match compiler, record package, 
1NTERSCOPE. 



iii 



The preparation of this manual has involved the efforts of several persons at 
Xerox PARC , whom I specifically want to mention, and to express my appreciation 
for their support through this arduous, and at times seemingly endless task. 
Thank you Suzan (Jerome), Janet (Farness), Peter (Deutsch), Bob (Walker), and 
Larry (Tesler). I couldn't have done it without you, 

• " ' ' Warren Tei'telman 

Palo Alto 
December, 1973 

n « & 

Special thanks go to R. L. Walker, L. M. Hasinter, and. L.; 'P.. Deutsch for 
assistance in the preparation of this first revision. 

' W.T. 
October, 1974. 



iv 



TABLE OF CONTENTS 



page 

SECTION 1: Introduction 

SECTION 2: Using INTERLISP 

Using the INTERLISP Manual . 1 

Using the INTERLISP-iO System on Tenex ............ 4 

SECTION 3: Data types, Storage Allocation, and Garbage 
Collection, and Overlays 

Data Types ..• . . 1 

Literal Atoms 2 

Pnames . 5 

Numerical Atoms ................. 0 ..... . 5 

Lists . . . 8 

Arrays 9 

Strings 10 

Storage Allocation and Garbage Collection 12 

Shared INTERLISP-iO ........ 15 

SECTION 4: Function Types and Implicit PROGN 

Exprs 1 

Compiled Functions .............. 3 

Function Type "... . .. 3 

PROGN 4 

Implicit PROGN . . .. . 4 

SECTION 5: Primitive Functions and Predicates 

Primitive Functions i 

RESETVAR and RESETFORM 9 

Predicates and Logical Connectives ................ 12 

SECTION 6: List Manipulation and Concatenation 

SECTION 7: Property Lists and Hash Links 

Property Lists . 1 

Hash Links 4 

Hash Overflow 7 



i 



TABLE OF CONTENTS (cont.) 



pas® 

SECTION 8: Function Definition and Evaluation 

SECTION! 9: The INTERLISP Editor 

Introduction • i 

Commands for the New User . .... 10 

Attention Changing Commands . . . 15 

Local Attention Changing Commands . . .. . 15 

Commands That Search ...... 21 

Search Algorithm . .... ....... 23 

Search Commands . .. . 25 

Location Specification 28 

Commands That Save and Restore the 

Edit' Chain' ....... . . . . . " 34 

Commands That Modify Structure 36 

Implementation of Structure Modification 

Commands ...... ;". . . . . . ..... ............ 3? 

The A, B, : Commands 3.9 

Form Oriented Editing and the Role of UP .... 43 

Extract and Embed ............. . 45 

The MOVE Command ................. 48 

Commands That "Move Parentheses* 9 51 

TO and THRU .................................. 54 

The R Command 57 

Commands That Print ............................... 60 

Commands That Evaluate . ... 62 

Commands That Test . . . . . . ...................... . . . . 64 

Macros 67 

Miscellaneous Commands 70 

UNDO 78 

EDITDEFAULT . . . . ....................... .... 80 

Editor Functions 83 



SECTION 10: Atom, String, Array, and Storage Manipulation 

Pnames and Atom Manipulation i 

String Functions 5 

Searching Strings ....................... 8 

String Storage 11 

Array Functions 12 

Storage Functions 14 



SECTION 11: Functions with Functional Arguments 

SECTION 12: Variable Bindings and Pushdown List Functions 

The Pushdown List and the Interpreter .. 3 

The Pushdown List and Compiled Functions .......... 6 

Pushdown List Functions ..................... . 7 

The Pushdown List and Funarg It 



ii 



TABLE OF CONTENTS (cont.) 



SECTION 13: Arithmetic Functions 

General Comments . . 1 

Integer Arithmetic 2 

Floating Point Arithmetic 6 

Nixed Arithmetic . .... 7 

Special Functions .„ 8 

Reusing Boxed Numbers in XNTERLISP-iO - SETN 10 

Box and Unbox 13 



SECTION 14: Input/Output Functions 

Files 1 

Addressable Files . . ... 5 

JFN Functions in INTERLISP-10 9 

Input Functions 11 

Output Functions 19 

Printlevel . ... 20 

Readtables and Terminal Tables 21 

Readtable Functions 22 

Syntax Classes . . 23 

Read-macro Characters 26 

Terminal Tables 28 

Terminal Control Functions 30 

Line-Buffering and Control 32 

Miscellaneous Input/Output Control Functions 35 

Sysin and Sysout 37 

Symbolic File Input 39 

File Maps 42 

Symbolic File Output 44 

PRETTYPRINT . . . . 45 

Comment Feature 40 

PRETTVDEF 47 

Special PRETTYPRINT Controls 55 

File Package 62 

Noticing Files 63 

Marking Changes 64 

Updating Files 65 

MAKEFILE 65 

Remaking a Symbolic File 67 



SECTION 15: Debugging - The Break Package 

Debugging Facilities 1 

BREAK 1 ......... 4 

Break Commands ............................... 7 

Brkcoms 15 

Brkfile . 15 

Breakmacros 16 

Breakresetforms 16 

Break Functions 17 

BREA&IN 21 



iii 



TABLE OF CONTENTS (cont.) 



EMS 

SECTION 10: Error Handling 

Unbound Atoms and Undefined Functions ..... 1 

Teletype Initiated Breaks ... . . .... 2 

Control H 2 

Control B . . . . 3 

Control E ....... . 3 

Other Types of Errors 4 

Breakcheck - When to Break 4 

Error Types . . . . . . . 7 

Error Handling by Error Type 12 

Error Functions , 13 

Interrupt Characters 16 



SECTION 17: Automatic Error Correction - The DWIM Facility 

Introduction 1 

Interaction with DWIH . 5 

Spelling Correction Protocol ................. 5 

Parentheses Errors Protocol 7 

Spelling Correction , .......................... . , 10 

Synonyms 11 

Spelling -Lists ........................ 12 

Error Correction 15 

Unbound Atoms 16 

Undefined Car of Form 17 

Undefined Function in Apply 18 

DWIMUSERFN 19 

Spelling Corrector Algorithm 20 

DWIM Functions 23 



SECTION 18: The Compiler and Assembler 

The Compiler 1 

Compiler Questions 3 

Nlambdas 5 

Global Variables . 6 

Compiler Functions 7 

DECLARE: ... .. II 

RECOMPILE 11 

Open Functions . ... 14 

Compiler Macros . , 16 

FUNCTION and Functional Arguments 18 

Block Compiling 19 

Specvars 19 

Localfreevars 20 

Retfns 21 

Blkapplyfns . 22 

Blklibrary 22 

Linked Function Calls 23 

Relinking . . . 27 

The Block Compiler 28 

BLOCKCOMPILE 29 

Block Declarations 30 

BCOMPL 32 



iv 



TABLE OF CONTENTS (com.) 



page 



BRECOMPILE 33 

Compiler Structure 35 

ASSEMBLE 36 

LAP . . . . 41 

using assemble "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!.. 47 

Miscellaneous . . 48 

Compiler Printout and Error Messages 49 



SECTION 19: Advising 

Implementation of Advising . ... 2 

Advise Functions 5 



SECTION 20: Printstructure, Interseope, and Helpsys 

Printstructure 1 

Interscope 10 

Helpsys . . # . . . 21 



SECTION 21: Miscellaneous 

Measuring Functions 1 

BREAKDOWN 5 

EDITA .... ...... 8 

Input Protocol . . 10 

EDITA commands and variables 12 

Interfork Communication in INTERLISP-10 . .. 18 

Subsys . . 19 

Miscellaneous TENEX Functions in INTERLISP-10 ..... 22 

Printing Reentrant and Circular List Structures ... 23 

Typescript files 30 



SECTION 22: The Programmer's Assistant and LISPX 

Introduction . . 1 

Overview 6 

Event Specification 11 

History Commands 14 

Implementation of REDO, USE, and FIX 17 

History Commands Applied to History Commands . 20 

History Commands That Fail 21 

More History Commands 22 

Miscellaneous Features and Commands ♦ 28 

Undoing 38 

Testmode 41 

Undoing out of order 42 

SAVESET 43 

Format and Use of the History List 44 

LISPX and READLINE 47 

Functions 48 

The Editor and the Assistant 61 

Statistics ..' 63 

Greeting and User Initialization 64 



v 



TABLE OF CONTENTS (com.) 



page 

SECTION 23: CUSP - Conversational LISP 

Introduction ...... . . . . . . 1 

CLISP Syntax ................. 9 

Infix Operators 10 

Prefix Operators . . 13 

Constructing Lists - the <,> Operators 16 

IF, THEN, ELSE . V • 1? 

Iterative Statements 18 

Errors in Iterative Statements 28 

Defining New Iterative Statement Operators ... 29 

CLISP Translations 31 

Declarations 35 

Local Declarations 37 

The Pattern Match Compiler 38 

Element Patterns 41 

Segment Patterns 43 

Assignments , 45 

Place-markers 46 

Replacements 46 

Reconstruction 4? 

Record Package 50 

Record Declarations 53 

CREATE 59 

Implementation 61 

CLISPIFY .. 62 

DWIMIFY 65 

Compiling CLISP 67 

Operation ......... 68 

CLISP Interaction with User .... . 71 

CLISP Internal Conventions 72 

CLISP Functions and Variables ... . 75 

APPENDIX 1: TRANSOR 

Introduction 1 

Using TRANSOR ., . ... 3 

The Translation Notes 4 

TRANSORSET . . . . 8 

Controlling the sweep 14 



APPENDIX 2: INTERLISP Interpreter 
APPENDIX 3: Control Characters 
MASTER INDEX 



vi 



SECTION 1 
INTRODUCTION 



This document is a reference manual for INTERLISP* a LISP system that is 
currently implemented on (or implementations are in progress for) at least five 
different machines. This manual is a reference manual for all INTERLISP 
implementations, although it does contain some material that is relevant only 
to LMTERLISP-10, the implementation of INTERLISP for the DEC PDP-iQ under the 
BBM TENEX time sharing system.[Bobl]* Where this is the case, .such material is 
clearly marked. 

INTERLISP has been designed to be a good on-line interactive system (from which 
it derives its name). Some of the features provided include elaborate 
debugging facilities with tracing and conditional breakpoints (Section 15), and 
a sophisticated LISP oriented editor within the system (Section 9). 
Utilization of a uniform error processing through user accessible routines 
(Section 16) has allowed the implementation of DWIM, a Do-What-J-Mean facility, 
which automatically corrects many types of errors without losing the context of 
computation (Section 17). The CLI5P facility (Section 23) extends the LISP 
syntax by enabling ALGOL-like infix operators such as -> /, = , AND, 
OR, etc., as well as IF-THEN-ELSE statements and FOR-WHILE-DO statements. 



INTERLISP-10 is designed to provide the user access to the large virtual 
memory allowed by TENEX, with relatively small penalty in speed (using 
special paging techniques described in [Bob2]). INTERLISP-10 also provides 
for essentially unlimited quantity of compiled code via the overlay 
facility described in section 3. INTERLISP-10 was the first 
implementation of INTERLISP, and is still the most widely used. 
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CLISP expressions are automatically converted to equivalent INTERLISP forms 
when they are first encountered, CLISP also includes a sophisticated pattern 
match compiler, as well as a record package that facilitiates "data-less" 
programming. 

* IMTERLISP has also been designed to be a flexible system. Advising (section 19) 
enables users to selectively modify or short-circuit any system function. Even 

* such "built-in" aspects of the system as interrupt characters, garbage 

* collection allocation and messages, output radix, action on various error 
+ conditions, line-buffering protocol, etc., all can be affected through system 

* functions provided for that purpose. Readtables and terminal tables (section 
+ 14) allow the user complete control over input, including the ability to define 

* read macro characters, specify echo modes, even redefine the action of 

* formatting characters such as parentheses. The user can also define new 

* datatypes (section 23) in addition to the lists, strings, arrays p and hash 
+ association tables (hash links) already provided. 

A novel and useful facility of the INTERLISP system is the programmer's 
assistant (Section 22), which monitors and records all user inputs. The user 
can instruct the programmer's assistant to repeat a particular operation or 
sequence of operations, with possible modifications, or to UNDO the effects of 
specif ied operations. The goal of the programmer 8 s assistant , DWIM, CLISP, 
etc. is to provide a programming environment which will "cooperate" with the 
user in the development of his programs, and free him to concentrate more fully 
on the conceptual difficulties and creative aspects of the problem he is trying 
to solve. 

To aid in converting to INTERLISP programs written in other LISP dialects, 
e.g., LISP 1.5, Stanford LISP, we have implemented TRANSOR, a subsystem which 
accepts transformations (or can operate from previously defined 
transformations), and applies these transformations to source programs written 
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in another LISP dialect, producing object programs which will run on INTERLISP 
(Appendix 1). In addition, TRANSOR alerts the programmer to problem areas that 
(may) need further attention. TRANSOR was used extensively in converting from 
940 LISP to BBM-LISP on the PDP-10. A set of transformations is available for 
converting from Stanford LISP and LISP 1,5 to INTERLISP. 

A complete format directed list processing system FLIP [Tail], is available for 
use within INTERLISP . 

Although we have tried to be as clear and complete as possible, this document 
is not designed to be an introduction to LISP. Therefore, some parts may only 
be clear to people who have had some experience with other LISP systems. A 
good introduction to LISP has been written by Clark Weissman [Weiij. Although 
not completely accurate with respect to INTERLISP, the differences are small 
enough to be mastered by use of this manual and on-line interaction. Another 
useful introduction is given by Berkeley [Beri] in the collection of Berkeley 
and Bobrow [Ber2]. 

Changes to this manual will be issued by replacing sections or pages, and 
reissuing the index and table of contents at periodic intervals. In addition, 
the manual will be maintained on-line, and up to date versions of any or all 
chapters will be available in machine readable form from W, Teitelman at Xerox 
PARC, 2 



INTERLISP-10 includes a limited question-answering facility, HELPSYS 
(section 20), that uses these files to interactively answer questions about 
INTERLISP . 
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First revision, October, 1974. 



The first revision to the INTERLISP reference manual corresponds to changes or 
additions to the INTERLISP system during the first ten months of 1974. 
Approximately 200 (out of 700) pages have been changed to some extent in this 
revision. A significant number of these (about 60 pages) occur in section 14 
(input/output). About 30 pages of chapter 23 (CUSP) have been changed* and 
the rest of the changes are scattered throughout the manual. Changed material 
in the text is flagged in the outside margin by the appearance of either a 
(for addition of completely new material), , - 1 (for deletion of original 
material), or (indicating changes to existing material that more or loss 

preserve its original structure.) Thus the reader who is already familiar with 
the INTERLISP manual can quickly determine what has been changed. Note: very 
few of these changes are not "upwards compatible 11 with the original manual, 
i.e. almost all of them represent extensions or additions. Nevertheless, the 
reader is encouraged to skim through the manual noting changes which may affect 
him. 

For those who do not wish to obtain an entire new manual, an update consisting 
of just the changed pages is available. 
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SECTION 2 
USING INTERLISP 



2.1 Using the INTERLISP Manual - Format, Notation, and Conventions 

The INTERLISP manual is divided into separate, more or less independent 
sections. Each section is paginated independently, to facilitate issuing 
updates of sections. Each section contains an index to key words, functions, 
and variables contained in that section. In addition, there is a composite 
index for the entire manual, plus several appendices and a table of contents. 

INTERLISP is currently implemented on (or implementations are in progress for) 
at least four different computers. This manual purports to be a reference 
manual for all implementations of INTERLISP, both present and future. However, 
since the largest user cummunity is still that of INTERLISP-10, the original 
implementation for the DEC PDP-10, the manual does contain some implementation 
dependent material. Where this is the case, the text refers to INTERLISP- 10 , 
and is indicated as such. 

Throughout the manual, terminology and conventions will be offset from the text 
and typed in italics, frequently at the beginning of a section. For example, 
one such notational convention is: 

The names of functions and variables are written in lower case and underlined 
when they appear in the text. Neta-LISP notation is used for describing forms. 

Examples: member[x;y] is equivalent to (MEMBER X Y), member! car[ x] ;FOO] is 
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equivalent to (MEMBER (CAR X) (QUOTE FOO)). Not© that in meta-LISP notation 
lower case variables are evaluated, upper case quoted. 

notation is used to distinguish between cons and list . 

e.g./ if x=(A 8 C), (FOO x) is (FOO (A B C)), whereas (FOO , x) 
is (FOO ABC). In other words, x is cadr of (FOO x) but cdr of (FOO . x) . 
Similarly, ^ is caddr of (FOO x y) > but cddr of (FOO x . y) . Note that this 
convention is in fact followed by the read program* 
i.e., (FOO . (A B C)) and (FOO A B C) read in as equal structures. 

Other important conventions are: 

TRUE in IMTBRLISP means not MIL. 

The purpose of this is to allow a single function to be used both for the 
computation of some quantity, and as a test for a condition. For example, the 
value of member[x;y] is either NIL, or the tail of j[ beginning with x. 
Similarly, the value of or is the value of its first TRUE, i.e., non-Nil, 
expression, and the value of and is either NIL, or the value of its last 
expression. 

Although most lists terminate in NIL, the occasional list that ends in an atom, 
e.g., (A B . C) or worse, a number or string, could cause bizarre effects. 
Accordingly, we have made the following implementation decision: 

All Junctions that iterate through a list. e.g.. member , length . mapc , etc. 
terminate by an nlistp check, rather than the conventional null~check. as a 
safety precaution against encountering data types which might cause infinite 
cdr loops . e.g. . strings, numbers* arrays. 

Thus, member[x;(A B . C) ]smember[x? (A B)] 
reverse[(A B . C) ]sreverse[ (A B)] 
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append[(A B . C ) ;y]sappend[ ( A B);y] 



For users with an application requiring extreme efficiency/ we have provided 
fast versions of memb , last , nth , assoc, and length which compile open and 
terminate on MIL checks, and therefore may cause infinite cdr loops if given 
poorly formed arguments. However, to help detect these situations, fmemb , 
f last , fnth , fassoc, and f length all generate errors when interpreted if their 
argument ends in a non-list other than NIL, e.g. BAD ARGUMENT - FLAST. 



Most functions that set system parameters, e.g., prtntlevel , I inelength , radix , 
etc.. return as their value the old setting. If given MIL as an argument, they 
return the current value without changing it. 

All SUBRS, I.e.. hand coded functions, such as read , print , eval , cons , etc.. 
have 'argument names' selected from U, V, A\ Y, Z, as described under 
arglist . Section 8. However, for tutorial purposes, more suggestive names are 
used in the descriptions of these functions in the text. 

Most functions whose names end in £ are predicates , e.g. numberp . tai I p. exprp i 
most functions whose names end in £ are nlambda' s , i.e., do not require quoting 
their arguments , e.g., setq , defineq , nlsetq . 

"x is equal to g" means equalixnj] is true, as opposed to "x is eg to n" 
meaning eq[xty] is true, i.e., x and g are the same identical LISP pointer. 

When new literal atoms are created (by the read program, pack , or mkatom ) . they 
are provided with a function definition cell initialized to tVIL (Section 8), a 
value cell initialized to the atom MOBIMO (Section 16), and a property list 
initialized to MIL (Section 7). The function definition cell is accessed by 
the functions getd and putd described in Section 8. The value cell of an atom 
is car of the atom, and its property list is cdr of the atom. In particular , 
car of MIL and cdr of MIL are always MIL, and the system will resist attempts 
to change them. 

The term list refers to any structure created by one or more conses. i.e. it 
does not have to end in MIL. For example. (A . B) is a list . The function 
listp , Section 5, is used to test for lists . Mote that not being a list does 
not necessarily imply an atom, e.g., strings and arrays are not lists, nor are 
they atoms. See Section 10. 

Many system functions have extra optional arguments for internal use that are 
not described in the writeups. For example, readline is described as a 
function of one argument , but arglist[ HEADLINE] returns (BDTBL LIME LISPXFLG) , 
In such cases, the user should just ignore the extra arguments. 



A NIL check can be executed in only one instruction, an nlistp on 
1MTERLISP-10 requires about 12, although both generate only one word of 
code. 
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INTERLISP departs from LISP 1.5 and other LISP dialects in that cor of a form 
is never evaluated. In other words, if car of a form is not an atom with a 
function definition, and not a function object/ i.e. a list car of which is 
LAMBDA, NLAMBDA, or FUNAR6, an error is generated, apply or apply * (section 8) 
must be used if the name of a function is to be computed as for example, when 
functional arguments are applied. 

2.2 Using the INTERLISP-10 System on TENEX - An Overview 

Call INTERLISP-IO by typing LISP followed by a carriage return. INTERLISP will 
type an identifying message , the date, and a greeting, followed by a This 
prompt character indicates that the user is "talking to" the top level 
INTERLISP executive, called evalqt . (for historical reasons), just as *(?' 
indicates the user is talking to TENEX. evalqt calls lispx which accepts 
inputs in either eval or apply format: if just one expression is typed on a 
line, it is eval uated; if two expressions are typed, the first is apply -ed to 
the second, eval and apply are described in section 8. In both cases, the 
value is typed, followed by * indicating INTERLISP is ready for another input. 

INTERLISP is normally exited via the function LOGOUT, i.e., the user types 
LOGOUT ( ) . However, typing control-C at any point in the computation returns 
control immediately to TENEX. The user can then continue his program with no 
ill effects with the TENEX CONTINUE command, even if he interrupted it during a 
garbage collection. Or he can reenter his program at evalqt with the TENEX 
REENTER command. The latte r is DEFINITELY not advisable i£ the Control-C was 
typed during a garbage collection . Typing control-D at any point during a 
computation will return control to evalqt . If typed during a garbage 
collection, the garbage collection will first be completed, and then control 
will be returned to INTERLISP' s top level, otherwise, control returns 
immediately. 
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When typing to the IWTERLISP read program, typing a control-Q will cause 
INTERLISP to print and clear the input buffer, i.e., ©rase the entire line 

up to the last carriage return. Typing control-A erases the last character 
typed in, echoing a \ and the erased character. Control-A will not back up 
beyond the last carriage return. Control-0 can be used to immediately clear 
the output buffer, and rubout to immediately clear the input buffer. In 
addition, typing control-U (in most cases) will cause the IWTERLISP editor 
(Section 9) to be called on the expression being read, when the read is 
completed. Appendix 3 contains a list of all control characters, and a 
reference to that part of the manual where they are described. Section 16 
describes how the system's interrupt characters can be disabled or redefined, 
as well as how the user can define his own interrupt characters. 

Since the IWTERLISP read program is normally line-buffered to make possible the 

action of control-Q, 5 the user must type a carriage return before any 

characters are delivered to the function requesting input, e.g., 

HE 1} 4 
T 

However, the read program automatically supplies (and prints) this carriage 
return when a matching right parenthesis is typed, making it unnecessary for 
the user to do so, e.g., 

«-CONS(A 8) 
(A . B) 



The action of control-Q takes place when it is read. If the user has 
'typed ahead' several inputs, control-Q will only affect at most the last 
line of input. Rubout however will clear the entire input buffer as soon 
as it is typed, i.e., even during a garbage collection. 

■■" 

Except following controi[T], see Section 14. 



'^' is used throughout the manual to denote carriage-return. 
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The INTERLISP read program treats square brackets as 'super-parentheses 1 : a 
right square bracket automatically supplies enough right parentheses to match 
back to the last left square bracket (in the expression being read), or if none 
has appeared, to match the first left parentheses/ 
e.g.; (A (B (C]=(A (B (C)))> 

(A [B (C (D] E)»(A (B (C (D))) E). 

% is the universal escape character for read. Thus to input an atom containing 
a syntactic delimiter, precede it by %, e.g. ABX (C or XX. See Section 14 for 

more details. 

tV (control-V) can be used to type a control character that would otherwise 
interrupt the input process, e.g. control-D, control-C, etc* If the character 
following tV is A, B, ... or Z, the corresponding control character is input, 
e.g. tVAtVBtVC is the atom control-Acontrol-Bcontrol-C. tV followed by any 
other character has no effect, i.e. FOOtVi and F001 are identical. For more 
details, see appendix 3. 

Most of the "basics" of on-line use of INTERLISP, e.g. defining functions, 
error handling, editing, saving your work, etc., are illustrated in the 
following brief console session. Underlined characters were typed by the user. 

1. The user calls INTERLISP from TENEX, INTERLISP prints a date, and a 
greeting. The prompt character ♦* indicates the user is at the top level of 

INTERLISP . 

2. The user defines a function, fact , for computing factorial of n. In 
INTERLISP, functions are defined via DEFINE or DEFINEQ, (Sections). 
Functions may independently evaluate arguments, or not evaluate them, and 
spread their arguments, or not spread them (Section 4). The function fact 
shown here is an example of "an everyday run-of-the-mill function of one 
argument, which is evaluated. 



g>lisp;> 



1 



INTERLISP-10 11-17-73 ... 
GOOD EVENING. 

-OEFINEQ( (FACT ( LAMBDDA ( H ) (COND ( (EQ H 0) NIL) 2 
(T (ITIHES N (FACTT (SUB1 N] 

(FACT) 

-(GETD (QUOTE FACT)) 3 
(LAMBDOA (N) (COND ((EQ N 0) NIL) (T (ITIMES N (FACTT (SUB1 N)))))) 
-FACT(3) A 
LAHBDDA [IN FACT] -> LAMBDA ? YES,? 
FACTT [IN FACT] -> FACT ? YES,?" 

NON-NUMERIC ARG 5 

NIL 

IN ITIMES 

(BROKEN) 6 

:BJ\? 

ITIMES 

COND 

FACT 

COND 

FACT 

COND 

FACT 

:N2 7 

1 

: EDITF ( FACT ) 8 
EDIT 

* ( R NIL 1) 9 
«0)Q 10 
FACT 

: RETURN 1) 11 

1 BREAK ' = 1 

6 

«- PP FACT,? 12 

(FACT 

[LAMBDA (N) 
(COND 

((EQ N 0) 
1) 

(T (ITIMES N (FACT (SUB1 N]) 
FACT 13 
«-PRETTYDEF( (FACT) FACT) 14 

FAcTTTI — 
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The user "looks 18 at the function definition. Function definitions in 
IMTERLISP are stored in a special cell called the function definition cell, 
which is associated with the name of the function (Section 8) . This cell 
is accessible via the two functions, getd and putd , ( define and def ineq use 
putd ). Note that the user typed an input consisting of a single 
expression, i.e. (GETD (QUOTE FACT)), which was therefore interpreted as a 
form for eval . The user could also have typed GETD(FACT) . 

The user runs his function. Two errors occur and corrections are offered 
by DWIN (Section 17). In each case, the user indicates his approval, DWIM 
makes the correction, i.e. actually changes the definition of fact , and 
then continues the computation. 

An error occurs that DWIM cannot handle, and the system goes into a break. 
At this point, the user can type in expressions to be eval-ed or apply-ed 
exactly as at the top level. The prompt character • indicates that the 
user is in a break, i.e. that the context of his computation is available. 
In other words, the system is actually "within" or "below" the call to 
itimes in which the error occurred. 

The user types in the break command, BT, which calls for a backtrace to be 
printed. In INTERLISP, interpreted and compiled code (see Section 18 for 
discussion of the compiler) are completely compatible, and in both cases, 
the name of the function that was called, as well as the names and values 
of its arguments are stored on the stack. Th® stack can be searched and/or 
modified in various ways (see Section 12). 

Break commands are discussed in Section 15, which also explains how the 
user can "break" a particular function, i.e. specify that the system go 
into a "break" whenever a certain function or functions are called. At 
that point the user can examine the state of the computation. This 
facility is very useful for debugging. 
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7. The user asks for the value of the variable n, i.e. the most recent value* 
or binding. The interpreter will search the stack for the most recent 
binding, and failing to find one, will obtain the top level value from the 
atom's value cell, which is car of the atom (Section 3). If there are no 
bindings, and the value cell contains the atom NOBIND, an unbound atom 
error is generated (Section 16). 

8. The user realizes his error, and calls the editor to fix it. (Note that 
the system is still in the break.) The editor is described at length and in 
detail in Section 9. It is an extremely useful facility of INTERL15P . 
Section 9 begins with a simple introduction designed for the new user. 

9 . The user instructs the editor to replace all NIL'S (in this case there is 
only one) by 1. The editor physically changes the expression it is 
operating on so when the user exits from the editor , his function, as it 
is now being interpreted, has been changed. 

10. The user exits from the editor and returns to the break. 

11. The user specifies the value to be used by itimes in place of NIL by using 
the break command RETURN. This causes the computation to continue, and 6 is 
ultimately returned as the value of the original input, fact(3). 

12. The user prettyprints (Section 14) fact , i.e. asks it be printed with 
appropriate indentations to indicate structure. Prettyprint also provides 
a comment facility. Note that both the changes made to fact by the editor 
and those made by DWIM are in evidence. 

13. The user writes his function on a file by using prettydef (Section 14), 
creating a TENEX file, FACT. 5 1 , which when loaded into INTERLISP at a later 
date via the function load (Section 14), will cause fact to be defined as 
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it currently is. There is also a facility in INTERLISP for saving and 
restoring an entire core image via the functions sysout and sysln 
(Section 14) . 

The user logs out, returning control to TENEX. However, he can still 
continue his session by re-entering INTERLISP via the TENEX REENTER or 
CONTINUE command. 
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APPLY[FN;ARGS] SUBR 2.4 
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EOUAL[X;Y] 2.3 
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EVAL[X] SUBR .. 2.4,8 

eval format 2.4 

EVALQT 2.4 

FASSOC[ X; Y] 2.3 

files 2.9 

FLAST[X] 2.3 

FLENGTH[ X] 2.3 

FMEMB[ X ; Y ] 2.3 

FNTH[ X ; N ] ..." 2.3 

function definition cell 2.3,8 

functional arguments 2.4 

garbage collection 2.4 

GETD[ X] SUBR 2.3,8 

interrupt characters 2.5 

LINELENGTH[ N ] SUBR 2.3 

line-buffering . . 2.5 

L1STP[X] SUBR 2.3 

lists , 2.3 

LOADC FILE ; LDFL.G ; PRINTFLG]* "!!!!!!!!!!!!!'!!!!!!!■!!! 2 .9 

LOGOUT[] SUBR 2.4 

NIL 2.2 

NLISTP[X] 2.2 

NOB I NO 2.3,9 

null-check 2.2 

predicates 2.3 
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PRETTYPRINT ........ 2.9 
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prompt character ........... 2.4,6,8 

property list . 2.3 

pushdown list , • • ♦ ♦ 2.8 

PUTD[X;Y] SUBR 2.3,8 

RADIX[N] SUBR 2.3 

REENTER "(ten-ex command) 2.4,10 

RETURN (break command) ...................... 2.9 

rubout 2.5 

square brackets 2.6 

SYSIN[ FILE ] SUBR 2.10 

SYSOUT[FILE] EXPR 2.10 

TENEX . 2.4,6,9-10 

true . . . . . 2.2 

user interrupt characters 2.5 

U.B.A. (error message) 2.9 

value cell 2.3 

variable bindings . 2.9 

p (carriage-return) 2.5 

## (typed by system) 2.5 
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: (typed by system) 2.8 

\ (typed by system) 2.5 

3 .... 2.6 

«- (typed by system) 2.4,6 
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SECTION 3 

DATA TYPES, STORAGE ALLOCATION, GARBAGE COLLECTION, AND OVERLAYS 1 

INTERLISP operates in an 18-bit address spaced This address space is divided 
into 512 word pages with a limit of 512 pages, or 262,144 words, but only that 
portion of address space currently in us© actually exists on any storage 
medium, INTERLISP itself and all data storage are contained within this 
address space. A pointer to a data element such as a number, atom, etc., is 
simply the address of the data element in this 18-bit address space. 

3 . 1 Data Types 

The data types of INTERLISP are lists, atoms, pnames, arrays, large and small 
integers, floating point numbers, string characters and string pointers. 
Compiled code and hash arrays are currently included with arrays. 

In the descriptions of the various data types given below, for e&ch data type, 
first the input syntax and output format are described, that is, what input 
sequence will cause the INTERLISP read program to construct an element of that 



This section was written by A. K. Hartley and J. VJ. Goodwin. 

INTERLISP is currently implemented on (or implementations are in progress 
for) at least four different machines. This section treats subjects that 
are for the most part somewhat implementation dependent. Where this is the 
case, the discussion refers to INTERLISP-10, the implementation for the DEC 
PDP-10, on which INTERLISP was first implemented. 

The user can also define new data types, as described in section 23. 
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type, and how the INTERLISP print program will print such an element. Next, 
those functions that construct elements of that data type are given. Note that 
some data types cannot be input, they can only be constructed, e.g. arrays. 
Finally, the format in which an element of that data type is stored in memory 
is described. 

3.1.1 Literal Atoms 

A literal atom is input as any string of non-delimiting characters that cannot 
be interpreted as a number. The syntatic characters that delimit atoms are 
space, end-of -line, 4 line-feed, % ( ) w ] and [. However, these characters may 
be included in atoms by preceding them with the escape character X. 

Literal atoms are printed by print and prin2 as a sequence of characters with 
%'s inserted before all delimiting characters (so that the atom will read back 
in properly). Literal atoms are printed by prinl as a sequence of characters 
without these extra Vs. For example* the atom consisting of. the five 
characters A, B, C, (, and D will be printed as ABC%(D by print and ABC (D '.by 
prinl . The extra %*s are an artifact of the print program; they are not stored 
in the atom's pname. 

Literal atoms can be constructed by pack , mkatom, and gensym (which uses 
mkatom) . 

Literal atoms are unique. In other words, if two literal atoms have the same 
pname, i.e. print the samfc, they will always be the same identical atom, that 
is, they will always have the same address in memory, or equivalently, they 



An end-of-line character is transmitted by TENEX when it sees a 
carriage-return. 
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will always be eg. Thus if pack or mkatom is given a list of characters 
corresponding to a literal atom that already exists, they return a pointer to 
that atom, and do not make a new atom. Similarly, if the read program is given 
as input of a sequence of characters for which an atom already exists, it 
returns a pointer to that atom. 



Note that this is not true for strings, large integers, floating point 
numbers, and lists, i.e. they all can print the same without being eg. 



A literal atom is a 3 word (36 bits) datum containing: 



WORD 



WORD 2: 



WORD 3: 



PROPERTY LIST 
(CDR) 


TOP LEVEL BINDING 
(CAR) 


0 




17 


18 35 




FUNCTION 


CALLING INSTRUCTION 


0 






35 


PNAME 


RESERVED FOR FUNCTIONS 
ON FILES 


0 




17 


18 35 



FIGURE 3-1 



Car of a literal atom, i.e. the right half of word 1, contains its top level 
binding, initially the atom NOBIND. Cdr of the atom is a pointer to its 

property list, initially NIL. 



Word 2, the function definition cell, is a full 36 bit word, containing an 
instruction to be executed for calling the function associated with that atom, 
if any. The left half differs for different function types (i.e., EXPR, SUBR, 
or compiled code); the right half is a pointer to the function definition.^ 



The pname cell, the left half of the third word, contains a pointer to the 
pname of the atom. The remaining half word is reserved for an extension of 
INTEElISP-10 to permit storing function definitions on files. 



This use of a full word saves some time in function calls from compiled 
code in that we do not need to look up the type of the function definition 
at call time. 
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3 . 1 .2 Pnames 



The pnames of atoms/ pointed to in the third word of the atom, comprise 
another data type with storage assigned as it is needed. This data type only 
occurs as a component of an atom or a string- It does not appear* for example, 
as an element of a list. 

Pnames have no input syntax or output format as they cannot be directly 
referenced by user programs. 

A pname is a sequence of 7 bit characters packed 5 to a word, beginning at a 
v/ord boundary. The first character of a pname contains its length; thus the 
maximum length of a pname is 126 characters. 

3.1.3 Numerical Atoms 

Numerical atoms, or simply numbers, do not have property lists, value cells, 
functions definition cells, or explicit pnames. There are currently two types 
of numbers in INTERLISP: integers, and floating point numbers. 

Integers 

The input syntax for an integer is an optional sign (■♦ or ») followed by a 



All INTERLISP pointers have pnames, since we define a pname simply to bo 
how that pointer is printed. However, only literal atoms and strings have 
their pnames explicitly stored. Thus, the use of the term pname in a 
discussion of data types or storage allocation means pnames of atoms or 
strings, and refers to a sequence of characters stored in a certain part of 
INTERLISP 8 s memory. 
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sequence of digits, followed by an optional Q.° If the Q is present, the digits 
are interpreted in octal, otherwise in decimal, e.g. 77Q and 63 both correspond 
to the same integers, and in fact are indistinguishable internally since no 
record is kept of how integers were created. 

The setting of radix (Section 14), determines how integers are printed: signed 
or unsigned, octal or decimal. 

Integers are created by pack and mkatom when given a sequence of characters 
observing the above syntax, e.g. (PACK (LIST 1 2 (QUOTE <?)))« 10. Integers 
are also created as a result of arithmetic operations, as described in Section 
13. 

An integer is stored in one 36 bit word; thus its magnitude must be less than 
2t35. 9 To avoid having to store (and hence garbage collect) the values of small 
integers, a few pages of address space P overlapping the INTBRLISP-10 machine 
language code, are reserved for their representation. The small number pointer 
itself, minus a constant, is the value of the number. Currently the range of 
•small* integers is -1536 thru 4-1535. The predicate smallp is used to test 
whether an integer is •small 1 . 

While small integers have a unique representation, large integers do not. In 
other words, two large integers may have the same value, but not the same 
address in memory, and therefore not be eg. For this reason the function eqp 
(or equal ) should be used to test equality of large integers. 



8 



9 



and terminated by a delimiting character. Note that some data types are 
self-delimiting, e.g. lists. 

If the sequence of digits used to create the integer is too large, the high 
order portion is discarded. (The handling of overflow as a result of 
arithmetic operations is discussed in Section 13.) 



3.6 



Floating Point Numbers 



A floating point number is input as a signed integer, followed by a decimal 

point, followed by another sequence of digits called the fraction, followed by 

to 

an exponent (represented by E followed by a signed Integer). Both signs are 
optional, and either the fraction following the decimal point, or the integer 
preceding the decimal point may be omitted. One or the other of the decimal 
point or exponent may also be omitted, but at least one of them must be present 
to distinguish a floating point number from an integer. For example, the 
following will be recognised as floating point numbers: 

5. 5.00 5.01 .3 5E2 5.1E2 

5E-3 -5.2E+6 

Floating point numbers are printed using the facilities provided by TENEX. 
XNTERLJSP-10 calls the floating point number to string conversion routines*^ 
using the format control specified by the function f Itfmt (Section 14). f Itfmt 
is initialised to T, or free format. For example, the above floating point 
numbers would be printed free format as: 

5.0 5.0 5.01 .3 500.0 510.0 

.005 -5.2E6 

Floating point numbers are also created by pack and rokatom » and as a result of 
arithmetic operations as described in section 13. 

A floating point number is stored in one 36 bit word in standard PDP-10 format. 
The range is *2.94E-39 thru £l.69E38 (or 2?-128 thru 2U27). 



and terminated by a delimiter. 

Additional information concerning these conversions may be obtained from 
the TENEX JSYS Manual. 
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3.1.4 Lists 



The input syntax for a list is a sequence (at least one) _ of INTERLISP data 
elements, e.g. literal atoms numbers, other lists, etc. enclosed in 
parentheses or brackets* A bracket can be used to terminate several lists, 
e.g. (A (B (C], as described in Section 2 . 

If there are two or more elements in a list, the final element can be preceded 
by a . (delimited on both sides), indicating that cdr of the final node in the 
list is to be the element immediately following the • , e.g. (A . B) or 
(ABC . D), otherwise cdr of the last node in a list will be NIL.* 3 Mote that 
the input sequence (ABC. NIL) is thus equivalent to (A B C), and that (A B . 
(C D) ) is thus equivalent to (A B C D). Note however that (A B . C D) will 
create a list containing the five literal atoms A B . C and D. 

Lists are constructed by the primitive functions cons and list . 

Lists are printed by printing a left parenthesis, and then printing the first 
element of the list,*^ then printing a space, then printing the second element, 
etc. until the final node is reached. Lists are considered to terminate when 
cdr of some node is not a list. If cdr of this terminal node is NIL (the usual 
case), car of the terminal node is printed followed by a right parenthesis. If 
cdr of the terminal nod® is not NIL, car of the terminal node is printed, 



12 



13 



14 



( ) is read as the atom NIL. 

Note that in INTERLISP terminology, a list does not have to end in NIL, it 
is simply a structure composed of one or more conses. 

The individual elements of a list are printed using prlnZ if the list is 
being printed by print or prln2, and by prlnl if the list is being printed 
by prinl . ^ ^ — 
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followed by a space, a period, another space, cdr of the terminal node, and 
then the right parenthesis. Mote that a list input as (A B C . NIL) will print 
as (A B C), and a list input as (A B , (C D)) will print as (A B C D). Mote 
also that printlevel affects the printing of lists to teletype, and that 
carriage returns may be inserted where dictated by linelength , as described in 
Section 14, 

A list is stored as a chain of list nodes , A list node is stored in one 36 bit 
word, the right half containing car of the list (a pointer to the first element 
of the list), and the left half containing cdr of the list (a pointer to the 
next node of the list). 

3.1,5 Arrays 

An array in INTERLISP is a one dimensional block of contiguous storage of 
arbitrary length. Arrays do not have input syntax; they can only be created by 
the function array . Arrays are printed by both print , prin2 , and prlnl , as 0 
followed by the address of the array pointer (in octal) • Array elements can be 
referenced by the functions elt and eltd , and set by the functions seta and 
setd , as described in Section 10. 

Arrays are partitioned into four sections; a header, a section containing 
unboxed numbers, a section containing INTERLISP pointers, and a section 
containing relocation information. The last three sections can each be of 
arbitrary length (including 0); the header is two words long and contains the 
length of the other sections as indicated in the diagram below. The unboxed 
number region of an array is used to store 36 bit quantities that are not 
INTERLISP pointers, and therefore not to be chased from during garbage 
collections, e.g. machine instructions. The relocation informaion is used when 
the array contains the definition of a compiled function, and specifies which 
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locations in the unboxed region of the array must be changed if the array is 
moved during a garbage collection. 

The format of an array is as follows: 



HEADER WORD 0 



WORD I 



FIRST DATA WORD 



ADDRESS OF RELOCATION 
INFORMATION 



USED BY GARBAGE 
COLLECTOR 



LENGTH 



ADDRESS OF POINTERS 



NON-POINTERS 



POINTERS 



RELOCATION 
INFORMATION 



The header contains: 

word 0 right 
left 

word 1 right 
left 



FIGURE 3-2 



length of entire block«ARRAYSIZE+2. 

address of relocation information relative to word 0 of 
block (> 0 if relocation information exists, negative 
if array is a hash array. 0 if ordinary array). 

address of pointers relative to word 0 of block. 

used by garbage collector. 



3.1.6 Strings 



The input syntax for a string is a followed by a sequence of any characters 
except " and %, terminated by a and % may be included in a string by 

preceding them with the escape character %. 
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Strings are printed by print and prin2 with initial and final sll s, and %»s 
inserted where necessary for it to read back in properly. Strings are printed 
by print without the delimiting " 'S and extra %'$. 

Strings are created by mkstring , substring , and concat. 

Internally a string is stored in two parts; a string pointer and the sequence 
of characters. The INTERLISP pointer to a string is the address of the string 
pointer. The string pointer, in turn, contains the character position at which 
the string characters begin, and the number of characters. String pointers and 
string characters are two separate data types, 15 and several string pointers 
may reference the same characters. This method of storing strings permits the 
creation of a substring by creating a new string pointer, thus avoiding copying 
of the characters. For more details, see Section 10. 

String characters are 7 bit bytes packed 5 to a word. The format of a string 
pointer is: 



OF CHARACTERS 5 * ADDRESS OF STRING + CHARACTER 
j POSITION 

0 14 15 35 

FIGURE 3-3 

The maximum length of a string is 32K (Ksl024) characters. 



String characters are not directly accessible by user programs. 
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3.2 Storage Allocation and Garbage Collection 



In the following discussion, we will speak of a quantity of memory being 
assigned to a particular data type, meaning that the space is reserved for 
storage of elements of that type. Allocation will refer to the process used 
to obtain from the already assigned storage a particular location for storing 
one data element. 

A small amount of storage is assigned to each data type when INTERLISP-iO is 
started; additional storage is assigned only during a garbage collection. 

The page is the smallest unit of memory that may be assigned for use by a 
particular data type. For each page of memory there is a one word entry in a 
type table. The entry contains the data type residing on the page as well as 
other information about the page, The type of a pointer is determined by 
examining the appropriate entry in the type table. 

Storage is allocated as is needed by the functions which create new data 
elements, such as cons , pack , mkstrlng . For example, when a large integer is 
created by iplus , the integer is stored in the next available location in the 
space assigned to integers. If there is no available location, a garbage 
collection is initiated, which may result in more storage being assigned. 

The storage allocation and garbage collection methods differ for the various 
data types. The major distinction is between the types with elements of fixed 
length and the types with elements of arbitrary length. List nodes, atoms, 
large integers, floating point numbers, and string pointers are fixed length; 
all occupy 1 word except atoms which use 3 words. Arrays, pnames, and strings 
(string characters) are variable length. 

Elements of fixed length types are stored so that they do not overlap page 
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boundaries. Thus the pages assigned to a fixed length type need not be 
adjacent. If more space is needed, any empty page will be used. The method of 
al locating storage for these types employs a free-list of available locations; 
that is, each available location contains a pointer to the next available 
location. A new element is stored at the first location on the free-list, and 
the free-list pointer is updated. 

Elements of variable length data types ore allowed to overlap page boundaries. 
Consequently all pages assigned to a particular variable length type must be 
contiguous. Space for a new element is allocated following the last space used 
in the assigned block of contiguous storage. 

When INTERLXSP-10 is first called, a few pages of memory are assigned to each 
data type. When the allocation routine for a type determines that no more 
space is available in the assigned storage for that type, a garbage collection 
is initiated. The garbage collector determines what data is currently in use 
and reclaims that which is no longer in use. A garbage collection may also be 
initiated by the user with the function reclaim (Section 10) . 

Data in use (also called active data) is any data that can be 'reached 1 from 
the currently running program (i.e., variable bindings and functions in 
execution) or from atoms. To find the active data the garbage collector 
•chases' all pointers, beginning with the contents of the push-down lists and 
the components (i.e., car , cdr, and function definition cell) of all atoms with 
at least one non-trivial component. 



The allocation routine for list nodes is more complicated. Each page 
containing list nodes has a separate free list. First a page is chosen 
(see CONS for details), then the free list for that page is used. Lists 
are the only data type which operate this way. 
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When a previously unmarked datum is encountered, it is marked, and all pointers 
contained in it are chased. Most data types are marked using bit tables; that 
is tables containing one bit for each datum. Arrays, however, are marked using 
a half-word in the array header. 

When the mark and chase process is completed, unmarked (and therefore unused) 
space is reclaimed. Elements of fixed length types that are no longer active 
are reclaimed by adding their locations to the free-list for that type. This 
free list allocation method permits reclaiming space without moving any data, 
thereby avoiding the time consuming process of updating all pointers to moved 
data. To reclaim unused space in a block of storage assigned to a variable 
length type, the active elements are compacted toward the beginning of the 
storage block, and then a scan of all active data that can contain pointers to 
the moved data is performed to update the pointers. 

Whenever a garbage collection of any type is initiated, i7 unused space for all 
fixed length types is reclaimed since the additional cost is slight. However, 
space for a variable length type is reclaimed only when that type initiated the 
garbage collection. 

If the amount of storage reclaimed for the type that initiated the garbage 
collection is less than the minimum free storage requirement for that type, the 
garbage collector will assign enough additional storage to satisfy the minimum 
free storage requirement. The minimum free storage requirement for each data 
may be set with the function minf s (Section 10). The garbage collector assigns 
additional storage to fixed length types by finding empty pages, and adding the 
appropriate size elements from each page to the free list. Assigning 



The 'type of a garbage collection 1 or the 'type that initiated a garbage 
collection' means either the type that ran out of space and called the 
garbage collector, or the argument to reclaim . 
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additional storage to a variable length type involves finding empty pages and 
moving data so that the empty pages are at the end of the block of storage 
assigned to that type. 

In addition to increasing the storage assigned to the type initiating a garbage 
collection, the garbage collector will attempt to minimise garbage collections 
by assigning more storage to other fixed length types according to the 
following algorithm. i8 If the amount of active data of a type has increased 
since the last garbage collection by more than 1/4 of the minfs value for that 
type, storage is increased (if necessary), to attain the minfs value. If 
active data has increased by less than i/4 of the minfs value P available 
storage is increased to 1/2 minfs. If there has been no increase, no more 
storage is added. For example, if the minfs setting is 2000 words, the number 
of active words has increased by 700, and after all unused words have been 
collected there are 1000 words available, 1024 additional words (two pages) 
will be assigned to bring the total to 2024 words available. If the number of 
active words had increased by only 300, and there were 500 words available, 512 
additional words would be assigned. 

3.3 Shared INTERLISP-10 

The INTERLISP-10 system initially obtained by the user is shared; that is, all 
active users of INTERLISP-10 are actually using the same pages of memory. As a 
user adds to the system, private pages are added to his memory. Similarly, if 
the user changes anything in the original shared INTERLISP-10, for example, by 
advising a system function, a private copy of the changed page is created. 



We may experiment with different algorithms. 
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In addition to the swapping time saved by having several users accessing the 
same memory, the sharing mechanism permits a large saving in garbage collection 
time, since we do not have to garbage collect any data in the shared system, 
and thus do not need to chase from any pointers on shared pages during garbage 
collections . 

This reduction in garbage collection time is possible because the shared system 
usually is not modified very much by the user. If the shared system is changed 
extensively, the savings in time will vanish, because once a page that was 
initially shared is made private, every pointer on it must be assumed active, 
because it may be pointed to by something in the shared system. Since every 
pointer on an initially shared but now private page can also point to private 
data, they must always be chased. 

A user may create his own shared system with the function makesys . If several 
people are using the same system, making the system be shared will result in a 
savings in swapping time. Similarly, if a system is large and seldom modified, 
making it be shared will result in a reduction of garbage collection time, and 
may therefore be worthwhile even if the system is only being used by one user. 

makesys[f ile] creates a saved file in which all pages in this 

system, including private user pages, are made 
read execute, i.e. shared. This system can then 
be run via the TENEX command RUN, or GET and 
START. 

For example, new INTERLISP-10 systems are brought up by loading the appropriate 
compiled files and then performing makesys[LISP.SAV].* 0 



makesys is also advised (see section 19) to set the variable makesysdate to 
(DATE), i.e. the time and date the system was made. — 
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herald[ string] makes string be the 'herald 8 for the system, i.e. 

the message printed when the system is first 
started. Primarily for ' use in conjunction with 
makesys . 



3.-4 The INTERLISP-10 Swapper * 4 

INTERLISP-10 provides a very large auxilary address space exclusively for 
swappable arrays (primarily compiled function definitions). In addition to the 
Z56K of resident address space, this "shadow space" can currently accomodate 
an additonal 256K words, can easily be expanded to 3.5 million words, and with 

some further modifications, could be expanded to 128 million words. Thus, the 

P2 

overlay system provides essentially unlimited space for compiled code. 



Shadow space and the swapper are intended to be more or less transparent to the 
user. However, this section is included in the manual to give programmers a 
reasonable feeling for what overlays are like, without getting unnecessarily 
technical, as well as to document some new functions and system controls which 
may be of interest for authors of exceptionally large systems. 



makesys is advised to set the variable heraldstring to the concatenation 
of "INTERLISP-IO" , the month and day of the makesys , and "..." and to call 
herald on this string. Alternatively, makesys can be given as a second 
argument a string to be used instead of "INTERLISP-10" , e.g. 
makesys[ S TREK .SAV ; STAR- TREK] would cause the message STAR-TREK followed by 
the date and "..." to be printed when STREK.SAV was run. 



The INTERLISP-10 swapper was designed by E. I. Wegbreit (PARC) and J. W. 
Goodwin (BBN), and implemented by J. W. Goodwin. 



Since compiled code arrays point to atoms for function names, and strings 
for error messages, not to mention the fact that programs usually have data 
base, which are typically lists rather than arrays, there is still a very 
real and finite limit to the total size of programs that INTERLISP-10 can 
accomodate. However, since much of the system and user compiled code can 
be made swappable, there is that much more resident space available for 
these other data types. 
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3.4,1 Overlays 

The shadow space is a very large auxiliary address space used exclusively for 
an IWTERLISP data type called a swappable array. The regular address space is 
called the "resident" space to distinguish it from shadow space. Any kind of 
resident array - compiled code, pointer data, binary data, or a hash array - 
can be copied into shadow space ("made swappable"), from which it is referred 
to by a one-word resident entity called a handle . The resident space occupied 
by the original array can then be garbage collected normally (assuming there 
are no remaining pointers to it, and it has not been made shared by a makesys ) . 
Similarly, a swappable array can be made resident again at any time, but of 
course this requires (re)allocating the necessary resident space. 

The main purpose and intent of the swapping system is to permit utilization oj 
swappable arrays directly and interchangeably with resident arrays , thereby 
saving resident space which is then available Jor other data types f such as 
lists, atoms, strings, etc. 

This is accomplished as follows: A section of the resident address space is 
permanently reserved for a swapping buffer. 23 When a particular swappable array 
is requested, it is brought (swapped) in by mapping or overlaying the pages of 
shadow space in which it lies onto a section of the swapping buffer. This 
process is the swapping or overlaying from which the system takes its name. 
The array is now (directly) accessible. However, further requests for swapping 
could cause the array to be overlaid with something else, so in effect it is 
liable to go away at any time. Thus all system code that relates to arrays must 
recognize handles as a special kind of array, fetch them into the buffer (if 
not already there), when necessary check that they have not disappeared, fetch 
them back in if they have, and even be prepared for the second fetch to bring 
the swappable array in at a different place than did the first. 



Currently 64 512 word pages. 
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The major emphasis in the design of the overlay system has been placed on 
running compiled code, because this accounts for the overwhelming majority of 
arrays in typical systems, and for as much as 60% of the overall data and code. 
The system supports the running of compiled code directly from the swapping 
buffer, and the function calling mechanism knows when a swappable definition is 
being called, finds it in the buffer if it is already there, and brings it in 
otherwise. Thus, from the user's point of view, there is no need to 
distinguish between swappable and resident compiled definitions P and in fact 
ccodep will be true for either, 

3.4.2 Non-Code Arrays 

The data-array functions { elt , seta , gethash , puthash , etc.,) do not yet 
recognize swappable arrays, and will generate ARG NOT ARRAY errors if called 
with one. This will be fixed someday, and then users will be free to copy 
resident data arrays into swappable ones or vice-versa. However, note that 
programs which generate and use pointers directly into the bodies of arrays, or 
take CAR or CDR of them, will not work, since they cannot fetch the array in, 
nor guarantee that it would not go away. 

3*4.3 Efficiency 

Once of the most important design goals for the overlay system was that 
swappable code should not execute any extra instructions compared to resident 
code, once it had been swapped in. Thus, the instructions of a swappable piece 
of code are identical (except for two instructions at the entry point) to those 
of the resident code from which it was copied, 24 and similarly when a swappable 



The relocatable instructions are indexed by a base register, to make them 
run equally well at any location in the buffer. The net slowdown due to 
this extra level of indirection is too small to measure accurately in the 
overall running of a program. On analytical grounds, one would expect it 
to be around 2%. 
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function calls another function (of any kind) it uses the exact same calling 
sequence as any other code. Thus, all costs associated with running of 
swappable code are paid at the point of entry (both calling and returning), 26 

The cost of the swapping itself, i.e. the fetch of a new piece of swapped code 
into the buffer, is even harder to measure meaningfully, since two successive 
fetches of the same function are not the same, due to the fact that the 
instance created by the first fetch is almost certain to be resident when the 
second is done, if no swapping is done in between. Similarly, two successive 
PMAP's (the Tenex operation to fetch one page) are not the same from one moment 
to another, even if the virtual state of both forks is exactly the same - a 
difficult constraint to meet in itself. 2 ^ Thus, all that can be reported is 
that empirical measurements and observations have shown no consistent slowdown 
in performance of systems containing swappable functionsp viz a viz resident 
functions . 

3.4.4 Specifications 

Associated with the overlay system is a datatype called a swparray , (numeric 
datatype 4), which occupies one word of resident space, plus however much of 
shadow space needed for the body of the array* arglist , fntyp , nargs, getd , 
putd , argtype , arraysize, changename, calls , printstructure, break , advise , and 



If the function in question does nothing, e.g. a compiled 
(LAMBDA NIL NIL), it costs approximately twice as much to enter its 
definition if it is swappable as compared to resident . However, very small 
functions are normally not made swappable (see mkswapp, page 3.21), 
because they don't save much space, and are (typically) entered frequently. 
Larger programs don't exhibit a measurable slow down since they amortize 
the entry cost over longer runs. 



The cost of fetching is probably not in the mapping operation itself but in 
the f irst reference to the page, which has a high probability of faulting. 
This raises the problem of measuring page fault activity, another morass of 
uncertainty. The BBN INTERLISP group has a project in progress to measure 
the interaction of INTERLISP-10 and TENEX, 
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edita all work equally well with swappable as resident programs, ccodep is true ♦ 

for all compiled functions/definitions. * 

swparray[n ;p ;v] Analogous to array . Allocates a swappable array. * 

swparrayp[x] Analogous to arrayp . Returns x if x is a swappable + 

array and, MIL otherwise. * 

mkswap[x] If x is a resident array, returns a swappable ♦ 

array which is a copy of x. If x is a literal + 

atom and ccodep [x] is true, its definition is <• 

copied into a swappable array, and it is * 

(undoably) redefined with the latter. The value * 

of mkswap is x. * 

mkunswap[x] the inverse of mkswap . x is either a swappable ❖ 

array, or an atom with swapped definition on its ♦ 

CODE property. ♦ 

mkswapp[fname;cdef ] All compiled definitions begin life as resident * 

arrays, whether they are created by load , or by * 

compiling to core. Before they are stored away * 

into their atom's function cell, mkswapp is * 

applied to the atom and the array. If the value + 

°^ mkswapp is T, the definition is made * 

swappable; otherwise, it is left resident. By ♦ 

redefining mkswapp or advising it, the user can * 

completely control the swappability of all future * 

definitions as they are created. The initial * 

definition of mkswapp will make a function * 

swappable if (1) noswapf Ig is NIL, and (2) the * 
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name of the function is not on noswapfns , and (3) 
the size of its definition is greater than 
mk swap size words, initially 128. 



setsbsize[n] Sets the size of the swapping buffer to n, a 

number of pages. Returns the previous value. 
setsbsize[] returns the current size without 
changing it. 27 



Currently, the system lacks error recovery routines for situations such as 
a call to a swappable function which is too big for the swapping buffer, or 
when the size is zero. Therefore, setsbsize should be used with care. 
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SECTION 4 
FUNCTION TYPES AND IMPLICIT PROGN 



In INTERLISP, each function may independently have: 

a. its arguments evaluated or not evaluated; 

b. a fixed number of arguments or an indefinite number of arguments; 

c. be defined by an INTERLISP expression,, by built-in machine code, or by 
compiled machine code. 

Hence there are twelve function types (2 x 2 x 3). 
4.1 Exprs 

Functions defined by INTERLISP expressions are called exprs . Exprs must begin 
with either LAMBDA or NLAMBDA, ^ indicating whether the arguments to the 
function are to be evaluated or not evaluated, respectively. Following the 
LAMBDA or NLAMBDA in the expr is the 'argument list', which is either 

(1) a list of literal atoms or NIL (fixed number of arguments); or 

(2) any literal atom other than NIL, (indefinite number of arguments). 

Case (1) corresponds to a function with a fixed number of arguments. Each atom 



Where unambiguous, the term expr is used to refer to either the function, 
or its definition. 
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in the list is the name of an argument for the function defined by this 
expression. When the function is called, its arguments will bd evaluated or 
not evaluated, as dictated by whether the definition begins with LAMBDA or 

2 

NLAMBDA, and then paired with these argument names. This process is called 
"spreading" the arguments, and the function is called a spread-LAMBDA or a 
spread-NLAMBDA. 

Case (2) corresponds to a function with an indefinite number of arguments. 
Such a function is called a nospread function. If its definition begins with 
M LAMBDA, the atom which constitutes its argument list is bound to the list of 
arguments to the function (unevaluated) , For example, if F00 is defined by 
(NLAMBDA X --), when (F00 THIS IS A TEST) is evaluated, X will be bound to 
(THIS IS A TEST). 

If a nospread function begins with a LAMBDA, indicating its arguments are to be 
evaluated, each of its n arguments are evaluated and their values stored on the 
pushdown list. The atom following the LAMBDA is then bound to the number of 
arguments which have been evaluated. For example, if F00 is defined by 
(LAMBDA X ) when (F00 A B C) is evaluated, A, B, and C are evaluated and X is 
bound to 3. A built-in function, arg[atm;m], is available for computing the 
value of the mth argument for the lambda-atom variable atm . arg is described 
in section 8. 



Note that the function itself can evaluate selected arguments by calling 
eval . In fact, since the function type can specify only that all arguments 
are to be evaluated or none are to be evaluated, if it is desirable to 
write a function which only evaluates some of its arguments, e.g. setq, the 
function is defined as an n lambda, i.e. no arguments are evaluated in the 
process of calling the function, and then included in the definition itself 
are the appropriate calls to eval * In this case, the user should also put 
on the property list of the function under the property INFO the value 
EVAL to inform the various system packages such as DWIM, CLISP, 
PRINTSTRUCTURE, etc., that this function in fact does evaluate its 
arguments, even though it is an nlambda. 
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4.2 Compiled Functions 



Functions defined by expressions can be compiled by the INTERLISP compiler, as 
described in section 18, "The Compiler and Assembler". In IMTERLISP-10 > 
functions may also be written directly in machine code using the ASSEMBLE 
directive of the compiler . Functions created by the compiler , whether from S- 
expressions or ASSEMBLE directives, are referred to as compiled functions. In 
IWTERLISP-10 , compiled functions may be resident or swappable, as described in 
section 3. 

4.3 Function Type 

The function fntyp returns the function type of its argument. The value of 
fntyp is one of the following 12 types: 

EXPR CEXPR 

FEXPR CFEXPR 

EXPR« CEXPR® 

FEXPR* CFEXPR 5 * 



SUBR 
FSUBR 
SUBR* 
FSUBR® 



The types in the first column are all defined by expressions. The types in the 
second column are compiled versions of the types in the first column, as 
indicated by the prefix C. In the third column are the parallel types for 
built-in subroutines. Functions of types in the first two rows have a fixed 
number of arguments, i.e., are spread functions. Functions in the third and 
fourth rows have an indefinite number of arguments, as indicated by the 
suffix * . The prefix F indicates no evaluation of arguments. Thus, for 
example, a CFEXPR* is a compiled form of a nospread-NLAMBDA. 
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A standard feature of the LVTERLISP system is that no error occurs if a spread 
function is called with too many or too few arguments. If a function is called 
with too many arguments, the extra arguments are evaluated hut ignored. If a 
function is called with too few arguments, the unsupplied ones will be 
delivered as MIL . In fact, the function itself cannot distinguish between 
being given MIL as an argument, and not being given that argument, e.g.. 
(FOO) and (FOO NIL) are exactly the same for spread functions. 



4.4 Progn 

progn is a function of an arbitrary number of arguments* progn evaluates the 
arguments in order and returns the value of the last, i.e., it is an extension 
of the function prog2 of LISP 1.5. Both cond and lambda/nlambda expressions 
have been generalised to permit 'implicit progns* as described below. 

4.5 Implicit Progn 

The conditional expression has been generalized so that each clause may contain 
n forms (n > 1) which are interpreted as follows: 

(COND 

(PI Ell E12 Eld) 

(P2 E21 E22) [1] 
<P3) 

(P4 E41)) 

will be taken as equivalent to (in LISP 1.5): 
(COND 

(PI (PROGN Ell E12 E13)) 

(P2 (PROGN E21 E22)) 

(P3 P3) [2] 

(P4 E41) 

(T NIL)) 

Note however that P3 is evaluated only once in [1], while it is evaluated a 
second time if the expression is written as in [2]. Thus a clause in a cond 
with only a predicate and no following expression causes the value of the 
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predicate itself, if non-NIL, to be returned. Note also that NIL is returned 
if all the predicates have value NIL, i.e., the cond 'falls off the end 1 . No 
error is generated. 

LAMBDA and N LAMBDA expressions also allow implicit progn 's; thus for example: 

(LAMBDA (VI V2) (Fl VI) (F2 V2) NIL) 
is interpreted as: 

(LAMBDA (VI V2) (PR06N (Fl VI) (F2 V2) NIL) ) 

The value of the last expression following LAMBDA (or NLAMBDA) is returned as 
the value of the entire expression. In this example, the function would always 
return NIL. 
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SECTION 5 
PRIMITIVE FUNCTIONS AND PREDICATES 



5.1 Primitive Functions 

car[x] car gives the first element of a list x, or the 

left element of a dotted pair x. For literal 
atom, value is top level binding (value) of the 
atom. For all other nonlists, e.g. strings, 
arrays, and numbers, the value is undefined (and 
on some implementations may generate an error). 



cdr[x] cdr gives the rest of a list (all but the first 

element). This is also the right member of a 
dotted pair. If x is a literal atom, cdr[x] gives 
the property list of x. Property lists are 
usually NIL unless modified by th© user. The 
value of cdr is undefined for other nonlists. 

caar[x] = car[car[x]] All 30 combinations of nested cars 

cadr[x] * car[cdr[x]J and cdrs up to 4 deep are included 

cddddr[x] = in the system. All are compiled 

cdr[cdr[cdr[cdr[x]]]] open by the compiler. 



cons[x;y] cons constructs a dotted pair of x and If ^ is 

a list, x becomes the first element of that list. 
To minimise drum accesses the following algorithm 
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is used in INTERL15P-10 , for finding a page on 
which to put thtf constructed INTERLISP word. 

cons[x;y] is placed 

1) on the page with £ if £ is a list and there is room; 
otherwise 

2) on the page with x if x is a list and there is room; 
otherwise 

3) on the same page as the last cons if there is room; 
otherwise 

4) on any page with a specified minimum of storage, presently 16 LISP 
words. 

conscount[] value is the number of conses since this INTERLISP 

was started up. 

rplacd[x;y] Places the pointer % in the decrement, i.e. cdr » 

of the cell pointed to by x. Thus it physically 
changes the internal list structure of x, as 
opposed to cons which creates a new list element. 
The only way to get a circular list is by using 
rplacd to place a pointer to the beginning of a 
list in a spot at the end of the list. 

The value of rplacd is x. An attempt to rplacd 
NIL will cause an error, ATTEMPT TO RPLAC NIL, 
(except for rplacd[NIL;NIL]) . For x a literal 
atom, rplacd[x;y] will make # be the property list 
of x. For all other non-lists, the effect of 
rplacd is undefined. 



5.2 



rplaca[x;y] similar to rplacd , but replaces the address 

pointer of x, i.e., car, with The value of 

rplaca is x. An attempt to rplaca NIL will cause 
an error, ATTEMPT TO RPLAC NIL, (except for 
rplaca[NIL;NIL]) . For x a literal atom, 
rplaca[x;y] will make % be the top level value for 
x. For all other non-lists, the effect of rplaca 
is undefined. 



Convention: Naming a Junction by prefixing an existing function name with £ 
usually indicates that the new function is a £ast version of the 
old, i.e.. one which has the same definition but compiles open and 
runs without any 'safety' error checks. 



f rplacd[x;y] 



Has the same definition as rplacd but compiles 
open as one instruction. Mote that no checks are 
made on x» so that a compiled frplacd can clobber 
NIL, producing strange and wondrous effects. 



f rplaca[x;y] 
quote[x] 



Similar to frplacd . 

This is a function that prevents its arguments 
from being evaluated. Its value is x itself, e.g. 
(QUOTE FOO) is F00. 1 



kwote[x] 



(LIST (QUOTE QUOTE) x), 

if x=A, and £=B, then 

(KWOTE (CONS x y))s (QUOTE (A . 8) ) 



Since giving quote more than one argument, e.g. (QUOTE EXPR (CONS X Y) ) , is 
almost always a parentheses error, and one that would otherwise go 
undetected, quote itself generates an error in this case, 
PARENTHESIS ERROR. 
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condCCj ;c 2 ; . . . ;c k ] 



selectqCxjyj, ;y 2 ; , . , ;y n ;z] 



The conditional function of INTERLISP, cond , takes 
an indefinite number of arguments Cj P c 2 , . c^, 
called clauses. Each clause is a list (e^ ... 
e ni ) of n > 1 items, where the first element is 
the predicate, and the rest of the elements the 
consequents. The operation of cond can be 
paraphrased as IF ©j 4 THEN e 21 ... e nl 

ELSEIF e 12 THEN e 22 ... e n2 ELSEIF e n 

The clauses are considered in sequence as follows: 
the first expression e^ of the clause c ± is 
evaluated and its value is classified as false 
(equal to NIL) or true (not equal to NIL). If the 
value of e ti is true, the expressions e 2i . . . e ni 
that follow in clause c± are evaluated in 
sequence, and the value of the conditional is the 
value of © n £» the last expression in the clause . 
In particular, if nsl, i.e., if there is only one 
expression in the clause c i# the value of the 
conditional is the value of e J;l . (which is 
evaluated only once). 

If e JA is false, then the remainder of clause c i 
is ignored, and the next clause is 
considered. If no e^ is true for any clause, the 
value of the conditional expression is NIL. 

selects a form or sequence of forms based on the 
value of its first argument x. Each is a list 
of the form ( § 2i ... e^ ) where s i is the 
selection key. The operation of selectq can be 
paraphrased ass 
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IF x=Sj THEN ... e k1 
ELSEIF x=s 2 THEN ... ELSE 2. 

If is an atom, the value of x is tested to soo 
if it is eg to (not evaluated). If so, the 
expressions e^ ... e^ are evaluated in sequence, 
and the value of the selectq is the value of the 
last expression evaluated, i.e. 

If s A is a list, the value of x is compared with 
each element (not evaluated) of s if and if x is eg 
to any one of them 9 then to ©^ are evaluated 
in turn as above. 

If ^ is not selected in one of the two ways 
described, is tested, etc., until all the £'s 

have been tested. If none is selected, the value 
of the selectq is the value of 2. z must be 
present. 

An example of the form of a selectq is: 

[SELECTQ (CAR X) 

(0 (PRINT FOO) 

(FIE X)) 
((A E I 0 U) 
(VOWEL X)) 
(COND 

((NULL X) 

NIL) 
(T (QUOTE STOP] 

which has two cases, Q and (A E I 0 U) and a 
default condition which is a cond. 



selectq compiles open, and is therefore very fast; 
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progl[x 1 ;x 2 ; . . . ;x n ] 



progn[x u ;x 2i ; . . . ;x n 3 



prog[args;e x ;e 2 ; . . . ;e R ] 



however, it will not work if the value of x is a 
list, a large integer, or floating point number, 
since selectq uses eg for all comparisons. 

evaluates its arguments in order, that is, first 
Xj, then x 2 , etc, and returns the value of its 
first argument Xj, e.g. (PR0G1 X (SETQ X Y) ) sets 
x to y, and returns x's original value. 

progn evaluates each of its arguments in order, 
and returns the value of its last argument as its 
value, progn is used to specify more than one 
computation where the syntax allows only one, e.g. 
(SELECTQ ... (PROGN ...)) allows ©valuation of 
several expressions as the default condition for a 
selectq . 

This function allows the user to write an ALGOL- 
like program containing INTERLISP expressions 
(forms) to be executed. The first argument, args , 
is a list of local variables (must be NIL if no 
variables are used). Each atom in args is treated 
as the name of a local variable and bound to NIL. 
args can also contain lists of the form 
(atom form). In this case, atom is the name of 
the variable and is bound to the value of form . 
The evaluation takes place before any of the 
bindings are performed, e.g., 

(PROG ((X Y) ( Y X) ) ...) will bind x to the value 
of x and % to the (original) value of x. 
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The rest of the prog is a sequence of non-atomic 
statements (forms) and atomic symbols used as 
labels for go. The forms are evaluated 
sequentially; the labels serve only as markers. 
The two special functions go and return alter this 
flow of control as described below. The value of 
the prog is usually specified by the function 
return . If no return is executed, i.e., if the 
prog "falls off the end," the value of the prog is 
NIL. 

go[x] go is the function used to cause a transfer in a 

prog . (GO L) will cause the program to continue 
at the label I. A go can be used at any level in 
a prog . If the label is not found, go will search 
higher progs within the same function, e.g. 
(PROG A (PROG — (GO A))). If the label is 
not found in the function in which the prog 
appears, an error is generated, UNDEFINED OR 
ILLEGAL GO. 

return[x] A return Is the normal exit for a prog . Its 

argument is evaluated and is the value of the prog 
in which it appears. 

If a go or return is executed in an interpreted function which is not a prog . 
the go or return will be executed in the last interpreted prog entered if any, 
otherwise cause an error. 

go or return inside of a compiled function that is not a prog is not allowed, 
and will cause an error at compile time. ^ 



As a corollary, go or return in a functional argument, e.g. to sort , will not 



work compiled. Also, since nlsetq 's and ersetq 's compile as separate 
functions, a go or return cannot be used inside of a compiled nlsetq or ersetq 
if the corresponding prog is outside, i.e. above, the nlsetq or ersetq . 



set[x;y] This function sets x to Its value is jr. If x 

is not a literal atom, causes an error, 
ARG NOT ATOM - SET. If x is NIL, causes an error, 
ATTEMPT TO SET NIL. Note that set is a normal 
lambda-spread function, i.e., its arguments are 
evaluated before it is called. Thus, if the value 
of x is c, and the value of x is b, then set[x;y] 
would result in c having value b, and b being 
returned as the value of set. 

setq[x;y] An nlambda version of set: the first argument is 

not evaluated, the second is. 2 Thus if the value 
of X is C and the value of Y is B, (SETQ X Y) 
would result in X (not C) being set to B, and B 
being returned. If x is not a literal atom, an 
error is generated, ARG NOT ATOM - SET. If x is 
NIL, the error ATTEMPT TO SET NIL is generated. 

setqq[x;y] Like setq except that neither argument is 

evaluated, e.g. (SETQQ X (A B C)) sets x to 
(A B C). 



Since setq is an nlambda, neither argument is evaluated during the calling 
process. However, setq itself calls eval on its second argument. Note 
that as a result, typing (SETQ var form) and SETQ(var form) to lispx is 
equivalent: in both cases var is not evaluated, and form is. 



5.8 



rpaq[x;y] like setg , except always works on top level 

binding of x, i.e. on the value cell. rpaq 
derives its name from rglaca Quote, since it is 
essentially an nlambda version of rplaca , e.g. 
(RPAQ F00 form) is equivalent to 

(RPLACA (QUOTE F00) form). 

rpaqq[x;y] like setqq for top level bindings. 

rpaq and rpaqq are used by prettydef (Section 14). Both rpaq and rpaqq 
generate errors if x is not atomic. Both are affected by the value of dfnf Ig 
(Section 8). if dfnf Ig s ALLPROP (and the value of x is other than NOBIND), 
instead of setting x, the corresponding value is stored on the property list of 
x under the property VALUE. 

Resetvar and Resetform 

resetvar[var ;new-value;form] The effect of resetvar is the same as 

(PROG ((var new«value)) (RETURN form)), except 
that resetvar is designed to work on GLOBAL 
variables, i.e. variables that must be reset, not 
rebound (see section 18). resetvar resets the 
variable (using frplaca ) , and then restores its 
value after evaluating form . The evaluation of 
form is errorset protected so that the value is 
restored even if an error occurs. resetvar also 
adds the old value of var to a global list, so 
that if the user types control-D (or equivalently 
in INTERLISP-10, control-C followed by REENTER) 
while form is being evaluated, the variable will 
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be restored by the top level INTERLISP executive. 
The value of resetvar is the value returned by 
form , if no error occurred. Otherwise, resetvar 
generates an error (after restoring the value of 
var) . resetvar compiles open. 

For example, the editor calls lispx to execute editor history 
commands by performing (RESETVAR LISPXHISTORY EDITHISTORY (LISPX --)). thereby 
making lispx work on edithistory instead of lispxhistory . 

The behavior of many system functions is affected by calling certain functions, 
as opposed to resetting variables, e.g. printlevel , linelength , input , output , 
radix , gcgag , etc. The function resetform enables a program to treat these 
functions much like variables, and temporarily change their "setting" . 

resetform[forml ;form2] nlambda, nospread, forml is evaluated, then f orm2 

is evaluated, then forml is 'restored* , e.g. 
(RESETFORM (RADIX 8) (F00)) will evaluate (FOO) 
while radix is 8, and then restore the original 
setting of radix. 

forml must return as its value its "previous 
setting" so that its effects can be undone by 
applying car of forml to this value. 

resetform is errorset protected like resetvar , and 
also records its information on a global list so 
that after control-D, forml is properly restored. 

The value of resetform is the value returned by 
f orm2 , if no error occurred. Otherwise, 
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resetform generates an error (after restoring 
forml). resetform compiles open. 

Since each call to resetvar or resetform involves a separate errorsot and somo 

additional overhead, the functions resetlst and resetsave provide a more 

efficient (and convenient) way of performing several resetvar s and/or 

resetform s at the same time. 

resetlst[resetx] nlambda, nospread. resetx is a list of forms. 

resetlst sets up the errorset so that any reset 
operations performed by resetsave are restored 
when the evaluation of resetx has been completed 
(or an error occurs, or a control-D is typed). 
The value of resetlst is the value of the last 
form on resetx , if no error occurs, otherwise 
resetlst generates an error (after performing the 
necessary restorations), resetlst compiles open. 

resetsave[ resetx] nlambda, nospread function for use under a 

resetlst . Combines functions of resetvar and 
resetform . If car of resetx is atomic, acts like 
resetvar , e.g. 
(RESETSAVE LISPXHISTORY E0ITHISTORY) resets the 
value of llspxhistory to be edithistory and 
provides for the original value of llspxhistory to 
be restored when the resetlst completes operation, 
(or an error occurs, or a control-D is typed). 
If car of resetx is not atomic, resetsave acts 
like resetform , e.g. (RESETSAVE (RADIX 8)) 
performs (RADIX 8), and provides for radix to be 
reset to its original value when the resetlst 
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completes. For functions which do not return 
their "previous setting", resetsave can be given 
the restoration expression as a second argument, 
e.g. 

[ RESETSAVE (SETBRK --)(LIST(QUOTE SETBRK )( GETBRK ] . 3 
(RESETSAVE NIL form) can be used to treat the 
value of form as a restoration expression, e.g. 
(RESETSAVE NIL (LIST (QUOTE CLOSEF) FILE) ) will 
cause file to be closed when the resetlst that the 
resetsave is under completes (or an error occurs 
or a control-D is typed). 

Note that resetsave provides a ivay of 
conditionally resetting a variable or form, e.g. 
(RESETLST (COND (-- (RESETSAVE — ))) -->. 

resetsave compiles open. Its value is not a 
•useful 1 quantity. 



5.2 Predicates and Logical Connectives 



atom[x] 



is T if x is an atom; NIL otherwise. 



litatom[x] 



is T if x is a literal atom, i.e 



an atom and not 



a number , NIL otherwise. 



niimberp[x] 



is x if x is a number, NIL otherwise. 



Note that restoration expressions are •evaluated 1 by applying their car to 
their cdr, as described under discussion of resetform . 
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Convention: Functions that end in £ are usually predicates . i.e. they test Jor 
some condition . 



stringp[x] is x if x is a string, NIL otherwise. 

arrayp[x] is x if x is an array, NIL otherwise, 

listp[x] is x if x is a list-structure, i.e., one created 

by one or more conses ; NIL otherwise. 



Mote that arrays and strings are not atoms, but are also not lists, i.e. both 
atom and listp will return MIL when given an array or a string. 



nlistp[x] not[listp[x]] 

eq[x;y] The value of eg is T, if x and £ are pointers to 

the same structure in memory, and MIL otherwise. 
eg is compiled open by the compiler. Its value is 
not guaranteed T for equal numbers which are not 
small integers. See eqp . 

neq[x;y] The value of ne§ is T, if x is not eg to and 

NIL otherwise. 

null[x] eq[x;NIL] 

not[x] same as null , that is eq[x;NIL]. 

eqp[x;y] The value of egj) is I if x and jj are eg, i.e. 



For other string functions, see Section 10. 
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pointers to the same structure In memory, or if x 
and % are numbers and are equal in valued Its 
value is NIL otherwise. 



equal[x;y] The value of equal is T (1) if x and % are eg, 

i.e. pointers to the same structure in memory; or 
(2) eqp , i.e. numbers with equal value; or (3) 
strequal , i.e. strings containing the same 
sequence of characters; or (4) lists and car of x 
is equal to car of and cdr of x is equal to cdr 
of jj. 6 The value of equal is NIL otherise. Note 
that x and # do not have to be eg. 

andCx^, ;x 2 ; . . . ;x n 3 Takes an indefinite number of arguments (including 

0). If all of its arguments have non-null value, 
its value is the value of its last argument, 
otherwise NIL. E.g. and[x;member£x;y]] will have 
as its value either NIL or a tail of and[]=T. 
Evaluation stops at the first argument whose value 
is NIL. 



or[Xj ;x 2 ; . . • ;x n ] Takes an indefinite number of arguments (including 

0). Its value is that of the first argument whose 
value is not NIL, otherwise NIL if all arguments 
have value NIL. E.g. or[x;numberp[y]] has its 
value x, or NIL. or[ ]*NIL. Evaluation stops at 
the first argument whose value is not NIL. 



For more discussion of eqp and other number functions, see Section 13. 

A loose description of equal might be to say that x and £ are equal if they 
print out the same way. 
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every[everyx;8veryfnl56veryfn23 Is T if the result of applying everyfnl 

to each element in everyx is true, otherwise NIL, 
E.g., every[(X Y Z); AT0M]=T. 



every operates by computing 

everyfnl[car[ everyx]]. If this yields NIL, every 
immediately returns NIL, Otherwise, every computes 
everyfn2[ everyx], or cdr[everyx] if everyfn2 sNIL, 
and uses this as the f new» everyx , and the process 
continues, e.g. every[x;ATOM;CDDR] is true if 
every other element of x is atomic, 

every compiles open. 

some[somex;somefnl ;somefn2] value is the tail of somex beginning with the 

first element that satisfies somefnl , i.e., for 
which somefnl applied to that element is true. 
Value is NIL if no such element exists. 
E.g., some[x;( LAMBDA (Z) (EQUAL Z Y) ) ] is 
equivalent to member[y;x]. some operates 
analagously to every . At each stage, 

somefnl[car[somex]$somex] is computed, and if this 
is not NIL, somex is returned as the value of 
some . Otherwise, somefn2[ somex] is computed, or 
cdr[ somex] if somefn2 gNIL, and used for the next 
somex . 

some compiles open. 



Actually, everyfnl[car[ everyx]; everyx] is computed, so for example everyfnl 
can look at the next element on everyx if necessary. 
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notany[somex;somefnl , somefn2] same as not[ some[ somex ; somef n 1 ; some f n2 ] ] 



no t e very[ e veryx ; everyf n 1 ; everyf n2 ] not[ every[ everyx ; everyf n 1 ; everyf n2 ] ] 



memb[x;y] 



Determines if x is a member of the list i.e., 
if there is an element of ^ S3 to x. If so, its 
value is the tail of the list % starting with that 
element. If not, its value is NIL. 



fmemb[x;y] 



Fast version of memb that compiles open as a five 
instruction loop, terminating on 6 NULL check. 
Interpreted, fmemb gives an error, 
BAD ARGUMENT - FMEMB, if £ ends in a non-list 
other than NIL. 



member[x;y] 



Identical to memb except that it uses equal 
instead of ejg[ to check membership of x in 



The reason for the existence of both memb and member is that eg compiles as one 
instruction but equal requires a function call* and is therefore considerably 
more expensive. Wherever possible, the user should write (and use) functions 
that use eg instead of equal . 



tailp[x;y] 



Is x,Hf x is a list and a tail of £, i.e., x is 

S 



eg to some number of cdrs > 0" of % 
otherwise. 



NIL 



assoc[x;y] 



is a list of lists (usually dotted pairs). The 
value of assoc is the first sublist of x whose car 



If x is eg to some number of cdrs > 1 of we say x is a proper tail. 
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is eg to x. If such a list is not found, the 
value is NIL. Example: 

assoc[B;((A . 1) (B . 2) (C . 3))] ■ (B .. 2). 

Fast version of assoc that compiles open as a 6 
instruction loop, terminating on a NULL check. 
Interpreted, fassoc gives an error if jr ends in a 
non-list other than NIL, BAD ARGUMENT - FASSOC. 



Same as assoc but uses equal instead of eg. 



Index for Section S 



Page 
Numbers 

ALLPROP ......... 5.9 

AND[X1 ;X2; . . . ;Xn] FSUBR* 5.14 

ARG NOT ATOM - SET (error message) .... 5.8-9 

ARRAYPCX] SUBR 5.13 

arrays . .' 5.13 

ASSOC[X;Y] 5.16 

ATOM[X] SUBR 5.12 

ATTEMPT TO RPLAC NIL (error message) ............ 5.2-3 

ATTEMPT TO SET NIL (error message) .............. 5.8 

BAD ARGUMENT - FASSOC (error message) ........... 5.17 

BAD ARGUMENT - FMEMB (error message) ... . 5.16 

CAR[X] SUBR .; 5.1 

CDR[X] SUBR 5.1 

COHD[ CI ;C2 jCn] FSUBR* 5.4 

cond clause 5.4 

CONS[X;Y] SUBR 5.1 

cons algorithm 5.2 

CONSCOUNT[N] SUBR 5.2 

control-D 5.9-10 

DFNFLG (system variable/parameter) 5.9 

dotted pair 5.1 

EO[X;Y] SUBR 5.13 

EOP[X;Y] SUBR 5.13 

EOUAL[X;Y] 5.14 

ERRORSET[U;V] SUBR 5.9 

ERSETQC ERSETX] NL 5.8 

EVERY[EVERYX;EVERYFN1;EVERYFN2] 5.15 

false 5.4 

FASSOC[X;Y] .. . 5.17 

FMEMB[ X ; Y] 5.16 

FRPLACA[ X ; Y] SUBR 5.3 

FRPLACDC X ; Y ] SUBR 5.3 

GCGAG[ MESSAGE] SUBR 5.10 

global variables 5.9 

GO[X] FSUBR* 5.7 

ILLEGAL RETURN (error message) 5.7 

INPUTCFILE] SUBR 5.10 

KWOTE[X] 5.3 

large integers 5.13 

LINELENGTH[N] SUBR 5.10 

LISTP[XJ SUBR 5.13 

lists 5.13 

LITATOM[ X] SUBR 5.12 

literal atoms 5.12 

local variables 5.6 

MEMB[ X ; Y ] 5.16 

MEMBER[ X ; Y] 5.16 

NEOCX;Y] 5.13 

NLISTP[X] 5.13 

NLSETQC NLSETX] NL 5.8 

NOB IND . ....... 5.9 

NOT[X] SUBR 5.13 

NOTANY[ SOMEX ;SOMEFNl ;SOMEFN2 ] 5.16 

NOTEVERY[ EVERYX;EVERYFN1 ;EVERYFN2] 5.16 

NULL[X] SUBR 5.13 

NUMBERP[X] SUBR 5.12 



INDEX. 5.1 



Page 
Numbers 



numbers 5.12 

0R[X1 ;X2; . . . ;Xn] FSUBR* 5.14 

OUTPUT[FILE] SUBR 5.10 

PARENTHESIS ERROR (error message) 5.3 

predicates 5.13 

PRETTYDEF 5.9 

PRINTLEVEL[N] SUBR 5.10 

PROG[ ARGS; El ;E2;...;En] FSUBR" 5.6 

PROG label 5.7 

PROGN[Xl;X2;...;Xn] FSUBR* 5.6 

PROGl[Xl;X2;...;Xn] FSUBR* 5.6 

proper tail 5.16 

0UOTE[X] NL* 5.3 

RADIX[N] SUBR 5.10 

REENTER ( tenex command) 5.9 

RESETFORM[ RESETX ; RESETY ; RESETZ] NL 5.10 

RESET LST[ RESETX] NL* 5.11 
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RETURN[X] SUBR 5.7 

RPAQ[RPAQX;RPAQY] NL 5.9 

RPAOO[X;Y] NL 5.9 
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SELECT0[X;Y1 ;Y2; . . . ;Yn;Z] NL" 5.4-5 

SET[X;Y] SUBR 5.8 

SETO[X;Y] FSUBR" 5.8 

SETQQ[ XSET ; YSET] NL 5.8 

small integers 5.13 

SOME[SOMEX;SOMEFN1;SOMEFN2] 5.15 

STRINGP[X] SUBR 5.13 

strings 5.13 

tail of a list 5.16 

TAILP[X;Y] 5.16 

top level value 5.1,3,9 

true 5.4 

UNDEFINED OR ILLEGAL GO (error message) 5.7 

(UNDEFINED TAG) (compiler error message) 5.7 

value cell 5.1,9 

VALUE (property name) 5.9 
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SECTION 6 
LIST MANIPULATION AND CONCATENATION 



lambda-nospread function. Its value is a list of 
the values of its arguments. 

append[x 1 ;x 2 ; . . . ;x n ] Copies the top level of the list x^ and appends 

this to a copy of top level list x 2 appended to 
. . . appended to x n> e.g. 

append[(A B) (C D E) (F 6)] = (A B C D E F 6). 

Note that only the first n-i lists are copied. 
♦ 

However ml is treated specially; i.e. append[x] 
can be used to copy the top level of a single 
list. 1 



Ixstfx^ t ^2 * • • • 5 ^ 



The following examples illustrate the treatment of 
non-lists. 

append[(A 8 C);D] - (ABC . 0) 
append[A;(B C D) ] "(BCD) 
append[(A B C . D);(E F 6)] ■ (ABC E F 6) 
append[(A B C . D)] « (A B C . D) 



To copy a list to all levels, use copy . 



nconcCxj ;x 2 ; . . . ;x n ] Returns same value as append but actually modifies 

the list structure of Xj . .. x n-l' 

* Mote that nconc cannot change NIL to a list. In other words, if the value of 

* foo is NIL/ then the value of (NCONC FOO (QUOTE (A B C))) is (A B C), but foo 

* will not have been changed. The 'problem 1 is that nconc simply has a 

* collection of pointers to work with, and does not know where they originally 
+ came from, i.e. does not know that this NIL is the value of foo, and while it 
+ is possible to alter list structure using rplaca , there is no May to .change a 
+ non-list to a list. 

nconcl[lst;x] Performs ncone[l$t;list[x]]. The cons will be on 

the same page as 1st. 

tconc[ptr;x] tconc is useful for building a list by adding 

elements one at a time at the end, i.e. its role 
is similar to that of nconcl . However, unlike 
nconc 1 , tconc does not have to search to the end 
of the list each time it is called. It does this 
by keeping a pointer to the end of the list being 
assembled, and updating this pointer after each 
call. The savings can be considerable for long 
lists. The cost is the extra word required for 
storing both the list being assembled, and the end 
of the list, ptr is that word: car[ptr] is the 
list being assembled, cdr[ptr] is last [car[ ptr]] . 
The value of tconc is ptr , with the appropriate 
modifications to car and cdr . Example: 

-(RPTQ 5 (SETQ FOO (TCONC FOO RPTN) ) ) 
((5 4 3 2 1)1) 
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tconc can be initialized in two ways. If ptr is 
NIL, tconc will make up a ptr . In this case, the 
program must set some variable to the value of the 
first call to tconc . After that, it is 
unnecessary to reset ptr since tconc physically 
changes it. Thus: 

-(SET F00 (TCONC NIL 1)) 
(d) 1) 

-(RPTQ 4 (TCONC FOO RPTN)) 
((14 3 2 1) 1) 

If p_tr is initially (NIL), the value of tconc is 
the same as for p_tr=NIL, but tconc changes ptr , 
e.g. 

-(SETQ FOO (CONS) ) 
(NIL) 

-(RPTQ 5 (TCONC FOO RPTN) ) 
((5 4 3 2 1) 1) 

The latter method allows the program to 
Initialize, and then call tconc without having to 
perform setq on its value. 

lconc[ptr ;x] Where tconc is used to add elements at the end of 

a list, lconc is used for building a list by 

adding lists at the end, i.e. it is similar to 
nconc instead of nconcl . e.g. 

-(SETQ FOO (CONS)) 
(NIL) 

-(LCONC FOO (LIST 12)) 
<(1 2) 2) 

-(LCONC FOO (LIST 3 4 5)) 
((12 3 4 5) 5) 
-(LCONC FOO NIL) 
((12 3 4 5) 5) 

Note that 

-(TCONC) FOO NIL) 
((1 2 3 4 5 NIL) NIL) 
-(TCONC FOO (LIST 3 4 5)) 
((12345 NIL (3 4 5)) (3 4 5)) 
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leone uses the same pointer conventions as tconc 
for eliminating searching to the end of the list, 
so that the same pointer can be given to tconc and 
Iconc interchangeably. 

attach[x;y] Value is equal to cons[x;y], but attaches x to the 

front of x by doing an rplaca and rplacd , i.e. 
the value of attach is eg to which it 

physically changes. ^ must be a list* or an error 
is generated, ILLEGAL ARG. 

remove[x;l] Removes all occurrences of x from list 1, giving a 

copy of 1 with all elements equal to x removed. 

Conventiont Naming a function by prefixing an existing function with d 
frequently indicates the new function is a destructive version of 
the old o/ie. i.e. it does not make any new structure hut 
cannibalizes its argument(s) . 

dremove[x;l] Similar to remove , but uses eg instead of equal , 

and actually modifies the list 1 when removing x, 
and thus does not use any additional storage. 
More efficient than remove . 

Note that dremove cannot change a list to NIL. For example, if the value of 
foo is (A), then (DREMOVE (QUOTE A) F00) will return NIL, and not perform any 
conses, but the value of foo will still be (A) because there is not way to 
change a list to a non-list. See discussion following description of nconc on 
page 6.2. 



copy[x] 



Hakes a copy of the list x. The value of copy is 



the copied list. All levels of x are copied, 
down to non-lists, so that if x contains arrays 
and strings, the copy of x will contain the same 
arrays and strings, not copies. Copy is recursive 
in the car direction only, so that very long lists 
can be copied. 



reverse[l] Reverses (and copies) the top level of a list, 

e.g. reverse[(A 8 (C D))] - ((C D) B A). If x is 
not a list, value is x, 

dreverse[l] Value is same as that of reverse , but dreverse 

destroys the original list 1 and thus does not use 
any additional storage. More efficient than 
reverse. 



sufost[x;y;z] Value is the result of substituting the S~ 

expression x for all occurrences of the S- 
expression £ in the S-expression 2. Substitution 
occurs whenever 2 ^ s equal to car of some 
subexpression of 2, or when y is both atomic and 
not NIL and ec| to cdr of some subexpression of z . 
For example: 

subst[A;B;(C B (X . B))] - (C A (X . A)) 
subst[A;(B C);((B C) D B C)] = (A D B C), 
not (A D . A). 

The value of subst is a copy of 2 with the 



To copy just the top level of x, do append[x]. 
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appropriate changes. Furthermore, if x is a list, 
it is copied at each substitution. 



dsubst[x;y ;2] 



Similar to subst , but does not copy 2, but changes 
the list structure z itself. Like subst , dsubst 
substitutes with a copy of x. Nor® efficient than 
subst. 



lsubst[x;y;z] 



Like subst except x is substituted as a segment, 
e.g. lsubst[(A B);Y;(X Y Z)3 is (X A B Z). Note 
that if x is NIL, produces a copy of z with all 
deleted. 



esubst[x;y;2;f Ig] 



Similar to dsubst, but first checks to see if 
actually appears in 2. If not, calls error! where 
flgsT means print a message of the form x ? This 
function is actually an implementation of the 
editor's R command (see Section 9), so that jj can 
use &, or alt-modes as with the R command. 



sublisCalst ;expr; fig] 



alst is a list of pairs: 

((Uj . Vj) (u 2 . v 2 ) ... (u n . v n )) with each u ± 



atomic. 



The value of sublis[ alst ;expr; fig] is the result 
of substituting each v for the corresponding u in 
expr . Example: 

Sublis[((A . X) (C . Y));(A B C D)] « (X B Y D) 



To remember the order on alst, think of it as old to new, i.e. u 1 -> 
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New structure is created only if needed, or if 
flcpT, e.g. if flcpNIl and there are no 
substitutions* value is ecj to expr . 



subpair[old;new;expr;f Ig] Similar to sublis , except that elements of now aro 

substituted for corresponding atoms of old in 
expr . Example: 

subpair[(A C);(X Y);(A BCD)] □ (X B Y D) 
As with sublis , now structure is created only if 
needed, or if f IgsT, e.g. if fJkpNIL and there are 
no substitutions, the value is eg to expr . 

If old ends in an atom other than NIL, the rest of 
the elements on new are substituted for that atom. 
For example, if old- (A B . C) and new»(U V X Y Z), 
U is substituted for A, V for 3, and (X Y Z) for 
C. Similarly, if old itself is an atom (other than 
NIL), the entire list new is substituted for it. 

Mote that subst , dsubst, Isubst , and esvbst all substitute copies of the 
appropriate expression, whereas subpair and sublis substitute the identical 
structure (unless flg ~T) . 

last[x] Value is a pointer to the last node in the list x, 

e.g. if xs(A B C) then last[x] a (C) . If 
x=(A B . C) last[x] s (B . C) . Value is NIL if x 
is not a list. 

. 

flast[x] Fast version of last that compiles open as a 5 

instruction loop, terminating on a null-check. 
Interpreted, generates an error, BAD ARGUMENT - 
FLAST, if x ends in other than NIL. 
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nleft[l;n;tail] Tail is a tail of 1 or NIL. The value of nleft is 

the tail of 1 that contains n more elements than 
tail . 4 e.g., if x»(A B C D E), nlef t[x;2]«( D E ) , 
nleft[x;l ;cddr[x]]=(B C D E). Thus nleft can be 
used to work backwards through a list. Value is 
NIL if 1 does not contain n more elements than 
tail . 

lastn[l;n] Value is cons[x;y] where £ is the last n elements 

of 1 P and x is the initial segment, e.g. 
lastn[(A BCD E);2]*((A B C) 0 E) 
lastn[(A B);2>(NIL A B). 

Value is NIL if 1 is not a list containing at 
least n elements. 

nth[x;n] Value is the tail of x beginning with the nth 

element, e.g. if n*2, value is cdr[x], if n=3„ 
cddr[x], etc. '.If n«l, value is x, if n«0 f ' for 
consistency, value is cons[NIL;x]. If x has fewer 
than n elements, value is NIL, e.g. 
nth[(A B);3]=NIL, as is nth[(A . B);3] Note that 
nth[(A . B);2]=B. 

fnth[x;n] Fast version of nth that compiles open as a 3 

instruction loop, terminating on a null-check. 
Interpreted, generates an error, BAD ARGUMENT - 
FNTH, if x ends in other than NIL. 





If tail is not NIL, but not a tail of 1, the result is the same as if tail 
were NIL, i.e. nleft operates by scanning 1 looking for tail , not by 
computing the lengths of 1 and tall. 
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length[x] 



Value is the length of the list x where length is 
defined as the number of cdrs required to reach a 
non-list, e.g. 

length[(A 8 C)] ■ 3 

length[(A B C . D)3 s 3 

length[A] ■ 0 



f length[x] 



Fast version of length that compiles open as a 4 
instruction loop, terminating on a null-check. 
Interpreted, generates an error, BAD ARGUMENT - 
FLENGTH, if x ends in other than NIL. 



count[x] 



Value is the number of list words in the structure 
Xo Thus, count is like a length that goes to all 
levels. Count of a non-list is 0. 



ldiff[x;y;z] 



£ must be a tail of x, i.e. eg to the result of 
applying some number of cdrs to x. Idif f [x;y] 
gives a list of all elements in x up to 2£» i.e., 
the list diff erence of x and j\ Thus 
ldiff[x;memb@r[F005x]3 gives all elements in x up 
to the first FOO. 



Note that the value of Idiff is always new list structure unless n*iVIL. in 
which case the value is x itself. 



If 2 is not NIL the value of Idif f is effectively 
nconc[z;ldiff[xsy]3, i.e. the list difference is 
added at the end of z. 



If x is a of 2£» generates an error, 
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LDIFF: NOT A TAIL, 
null-check. 



Idif f terminates on a 



intersection[x;y] Value is a list whose elements are members of both 

lists x and £. Note that intersection[x;x] gives 
a list of all members of x without any 
duplications. 

union[x;y] Value is a (new) list consisting of all elements 

included on either of the two original lists. It 
is more efficient to make x be the shorter list. 6 

data is a list of items to be sorted using 
comparefn , a predicate function of two arguments 
which can compare any two items on data and return 
T if the first one belongs before the second. If 
comparefn is NIL, alphorder is used; thus 
sort[data] will alphabetize a list. If comparefn 
is T, car 's of items are given to alphorder ; thus 
sort[a~list$T] will alphabetize by the car of each 
item. sort[x$IL£SSP] will sort a list of 
integers. 

The value of sort is the sorted list. The sort is 
destructive and uses no extra storage. The value 



sort[ data ; comparefn J 



6 



The value of union is £ with all elements of x not in % cons ed on the front 

of it. Therefore, if an element appears twice in jj, it will appear twice 

in union[x;y]. Also, since union[(A);(A A)] * (A A), while 

union[(A A);(A)] = (A), union is non-commutative. 

Sort, merge , and alphorder were written by J. W. Goodwin. 
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returned is eg to data but elements have been 
switched around. Interrupting with control D, E, 
or B may cause loss of data, but control H may bo 
used at any time, and sort will break at a clean 
state from which t or control characters are safe. 
The algorithm used by sort is such that the 
maximum number of compares is n^logg n> where n is 
length[data]. 



Note: ij comparefn[aib] * comparefn[b;a] . then the ordering of a and b may or 
may not be preserved . 

For example, if (FOO . FIE) appears before (F00 . FUH) in x, sort[x$T] may or 
may not reverse the order of these two elements. Of course, the user can 
always specify a more precise comparefn . 

merge[a ;b ;comparefn] a and b are lists which have previously been 

sorted using sort and comparefn . Value is a 
destructive merging of the two lists. It does not 
matter which list is longerAf ter merging both a 
and b are equal to the merged list In fact, cdr[ a] 
is ecf to edr[b]). merge may be aborted after 
control H. 

alphorder[a;b] A predicate function of two arguments, for 

alphabetising. Returns T if its arguments are in 
order, i.e. if b does not belong before a. 
Numbers come before literal atoms, and are ordered 
by magnitude (using greaterp ) . Literal atoms and 
strings are ordered by comparing the (ASCII) 
character codes in their pnames. Thus 
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alphorder[23;123] is T t whereas 

alphorder[A23;A123] is NIL, because the character 
code for the digit 2 is greater than the code for 
1. 

Atoms and strings are ordered before all other 
data types. If neither a nor b are atoms or 
strings, the value of alphorder is T, i.e. in 
order. 

Mote: alphorder does no unpacks , chcons . conges or nthchars , It is several 
times faster for alphabetizing than anything that can be written using 
these other functions . 

cplists[x;y] compares x and £ and prints their differences, 

i.e. cplists is essentially a SRCCOM for list 
structures. 
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SECTION 7 
PROPERTY LISTS AND HASH LINKS 



7 . 1 Property Lists 



Property lists are entities associated with literal atoms, and are stored on 
cdr of the atom. Property lists are conventional ly lists of the form (property 
value property value ... property value) although the user can store anything 
he wishes in cdr of a literal atom* However, the functions which manipu late 
property lists observe this convention by cycling down the property lists two 
cdrs at a time. Most of these functions also generate an error, ARCf NOT ATOM, 
if given an argument which is not a literal atom, i.e.. they cannot be used 
directly on lists . 

The term 'property name' or 'property 9 is used for the property indicators 
appearing in the odd positions, and the term 'property value' or 9 value of a 
property' or simply 'value' for the values appearing in the even positions. 
Sometimes the phrase 'to store on the property is used, meaning to place 
the indicated information on the property list under the property name — . 

Properties are usually atoms, although no checks are made to eliminate use of 
non-atoms in an odd position. However, the property list searching functions 
all use eg . 



Property List Functions 

put[atm;prop;val] puts on the property list of atm, the property 

prop with value y a 1 . val replaces any previous 
value for the property prop on this property list. 
Generates an error, ARG NOT ATOH, if aim is not a 
literal atom. Value is val. 

putl[ 1st ;prop;val] similar to gut except operates on lists instead of 

property lists. Searches ljst one cdr at a time 
looking for an occurrence of prop . If one is 



7.1 



addprop[ atm; prop; new; fig] 



remprop[atm;prop] 



changeprop[x;propl ;prop2] 



found, val replaces the next element in the list. 
If prop is not found, adds prop followed by val at 
the end of 1st. For example, putl[NIL;A;B]»( A B), 
putl[(A B C D);B;X]»(A B X D), 

adds the value new to the list which is the value 
of property prop on property list of atm. If fig 
is T, new is consed onto the front of value of 
prop , otherwise it is nconc ed on the end (nconcl ) . 
If atm does not have a property prop , the effect 
is the same as put[atm;prop; list[new]], for 
example, if addprop[FOO;PROP;FIE] is followed by 
addprop[FOO;PROP;FUM], getp[FOO;PROP] will 
be (FIE FUM). The value of addprop is the (new) 
property value. If atm is not a literal atom, 
generates an error, ARG NOT ATOM. 

removes all occurrences of the property prop (and 
its value) from the property list of atm. Value 
is prop if any were found, otherwise MIL . If atm 
is not a literal atom, generates an error, 
ARG NOT ATOM, 

Changes name of property propl to prop2 on 
property list of x, (but does not affect the value 
of the property). Value is x P unless propl is not 
found, in which case, the value is NIL. If x is 
not a literal atom, generates an error, 
ARG NOT ATOM. 



get[x;y] 



Gets the item after the atom y on list x. If y is 



not on the list x» value is MIL. For example, 
get[(A B C D);B>C. get and putl are inverse 
operations. 



Note: since get terminates on a non«list t get[atomtanything] is NIL. 



Therefore, to search a property list, getp should 
be usedp or get applied to cdr[atom]. 

getp[atm;prop] gets the property value for prop from the property 

list of atm . The value of getp is NIL if atm is 
not a literal atom, or prop if not found. 



Note: the value of getp may also be NIL. if there is an occurrence of prop but 
the corresponding property value is NIL. 



Note: Since getp searches a list two items at a 
time, the same object can be used as both a 
property name and a property value, e.g., if the 
property list of atm is (PROP! A PROP2 B A C ) , 
then getp[atm;A] » C. Not© however that 
get[cdr[atm]$A] = PR0P2. 

getlis[x;props] searches the property list of x» and returns the 

property list as of the first property on props 
that it finds e.g., if the property list of x is 
(PR0P1 A PR0P3 B A C). 
getlis[x;(PR0P2 PR0P3) ]=( PR0P3 B A C) 
Value is NIL if no element on props is found, x 
can also be a list itself, in which case it is 
searched as above. 
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def list[ 1 ;prop] is used to put values under the same property name 

on the property lists of several atoms. 1 is a 
list of two-element lists; The first element of 
each is a literal atom, and the second element is 
the property value for the property prop . The 
value of def list is NIL. 

Mote: Many atoms in the system already have property lists, with properties 
used by the compiler, the break package, DWIM. etc. Be careful not to 
clobber such system properties . The value of sysprops gives the complete 
list of the property names used by the system. 



7.2 Hash Links 

The description of the hash link facility in INTERLISP is included in the 
chapter on property lists because of the similarities in the ways the two 
features are used. A property list provides a way of associating information 
with a particular atom. A hash link is an association between any INTERLISP 
pointer (atoms, numbers, arrays, strings, lists, et al) called the hash-item, 
and any other INTERLISP pointer called the hash-value. Property lists are 
stored in cdr of the atom. Hash links are implemented by computing an address, 
called the hash-address, in a specified array, called the hash-array, and 
storing the hash-value and the hash-item into the cell with that address. The 
contents of that cell, i.e. the hash-value and hash-item, is then called the 
hash-link. 1 

Since the hash-array is obviously much smaller than the total number of 



The term hash link (unhyphenated) refers to the process of associating 
information this way, or the 'association' as an abstract concept. 
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possible hash-items, the hash-address computed from item may already contain a 
hash-link. If this link is from item, 3 the new hash-value simply replaces the 
old hash-value. Otherwise, another hash-address (in the same hash-array) must 
be computed, etc, until an empty cell is found, 4 or a cell containing a 
hash-link from item . 

When a hash link for item is being retrieved, the hash-address is computed 
using the same algorithm as that employed for making the hash link. If the 
corresponding cell is empty, there is no hash link for item . If it contains a 
hash-link from item, the hash-value is returned. Otherwise, another 
hash-address must be computed, and so forth. 6 

Mote that more than one hash link can be associated with a given hash-item by 
using more than one hash-array. 



Hash Link Functions 

In the description of the functions below, the argument array has one of three 
forms: (1) NIL, in which case the hash-array provided by the system, 



which is the total number of INTERL1SP pointers, i.e. in IWTERLISP- 10 , 
256K. 

eg is used for comparing item with the hash-item in the cell. 

After a certain number of iterations (the exact algorithm is complicated), 
the hash-array is considered to be full, and the array is either enlarged, 
or an error is generated, as described below in the discussion of overflow. 

For reasonable operation, the hash array should be ten to twenty percent 
larger than the maximum number of hash links to be made to it. 
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syshasharray , is used; 0 (2) a hash-array created by the function harray; or (3) 
a list car of which is a hash-array. The latter form is used for specifying 
what is to be done on overflow, as described below. 

harray[n] creates a hash-array of sise n, equivalent to 

clrhash[array[n]]. 

clrhash[array] sets all elements of array to 0 and sets left half 

of first word of header to -1. Value is array . 

puthash[ item;val ;array] puts into array a hash-link from item to val. 

Replaces previous link from same item, if any. If 
val sNIL any old link is removed, (hence a 
hash-value of NIL is not allowed). Value is val. 

finds hash-link from item in array , and returns 
the hash-value. Value is NIL if no link exists. 
gethash compiles open. Note that gethash makes 
no legality checks on either argument. 

hashes all items and values in oldar into newar . 
The two arrays do not have to be (and usually 
aren't) the same size. Value is newar . 

maphfn is a function of two arguments. For each 
hash-link in array , maphfn will be applied to the 
hash-value and hash-item, e.g. 



gethash[ item;array] 

ft 

rehash[ oldar ; newar] 



maphash[ array ;maphfn] 



syshasharray is not used by the system, it is provided solely for the 
user's benefit. It is initially 512 words large, and is automatically 
enlarged by 50% whenever it is 'full*. See page 7.7. 
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maphash[a;(LAMBDA(X Y) (AND(LISTP Y) (PRINT X)))] 
will print the hash-value for all hash-links from 
lists. The value of maphash is array . 



dmphashC arrayname] 



Nlambda-nospread that prints on the primary output 
file a load able form which will restore what is in 
the hash-array specified by arrayname , e.g. 
(E (DMPHASH SYSHASHARRAY) ) as a prettydef command 
will dump the system hash-array. 



Mote: all «eg[ identities except atoms and small integers are lost by dumping and 
loading because read will create new structure for each item. Thus if 
two lists contain an eg substructure , when they are dumped and loaded 
back in, the corresponding substructures while equal are no longer eg . 



Hash Overflow 

By using an array argument of a special form, the user can provide for 
automatic enlargement of a hash-array when it overflows, i.e., is full and an 
attempt is made to store a hash link into it. The array argument is either of 
the form (hash-array . n), n a positive integer; or (hash-array . f), f a 
floating point number; or (hash-array). In the first case, a new hash-array is 
created with n more cells than the current hash-array. In the second case, the 
new hash array will be f times the size of the current hash-array. The third 
case, (hash-array), is equivalent to (hash-array . 1.5). In each case, the now 
hash-array is rplaca ed into the dotted pair, and the computation continues. 

If a hash-array overflows, and the array argument used was not one of these 



circlprint and circlmaker (Section 21) provide a way of dumping and 
reloading structures containing eg substructures so that these identities 
eyre preserved. 
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three forms, the error HASH TABLE FULL is generated, which will either cause a 
break or unwind to the last errorset. as per treatment of errors described in 
Section 16. 

The system hash array, syshasharray , is automatically enlarged by 1.5 when it 
is full. 
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SECTION 8 
FUNCTION DEFINITION AND EVALUATION 



General Comments 

A function definition in INTERLISP is stored In a special cell called the 
function definition cell,, which is associated with each literal atom. This 
cell is directly accessible via the two functions putd , which puts a definition 
in the cell, and getd which gets the definition from the cell. In addition, 
the function fntyp returns the function type, i.e., EXPR P EXPR* ... FSUBR* as 
described in Section 4. Exprp 8 eeodep 9 and subrp are true if the function is 
an expr, compiled function, or subr respectively? argtype returns 
0, 1, 2, or 3, depending on whether the function is a spread or nospread (i.e., 
its fntyp ends in ®) 9 or evaluate or no-evaluate (i.e., its fntyp begins with F 
or CF); arglist returns the list of arguments; and nargs returns the number of 
arguments. fntyp , exprp , ccodep , subrp , argtype , arglist , and nargs can be 
given either a literal atom, in which case they obtain the function definition 
from the atom's definition cell, or a function definition itself. 

Subrs 

Because subrs, 1 are called in a special way, their definitions are stored 



Basic functions, handcoded in machine language, e.g. cons , car , cond . The 
terms subr includes spread/nospread, eval/noeval functions, i,e. the four 
fntyp 's SUBR, FSUBR, SUBR*, and FSUBR*. 
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differently than those of compiled or interpreted functions. In INTERLISP-10 , 
in the right half of the definition cell is the address of the first 
instruction of the subr, and in the left half its argtype : 0,1, 2, or 3, getd 
of a subr returns a dotted pair of argtype and address. Note that this is not 
the same word as appears in the definition cell, but a new cons ; i.e., each 
getd of a subr performs a cons . Similarly, putd of a definition of the form 
(number . address), where number = 0, 1, 2, or 3, and address is in the 
appropriate range, stores the definition as a subr, i.e., takes the cons apart 
and stores car in the left half of the definition cell and cdr in the right 
half. 

Validity of Definitions in INTERLISP-10 

Although the function definition cell is intended for function definitions, 
putd and getd do not make thorough checks on the validity of definitions that 
"look like" exprs, compiled code, or subrs. Thus if putd is given an array 
pointer, it treats it as compiled code, and simply stores the array pointer in 
the definition cell, getd will then return the array pointer. Similarly, a 
call to that function will simply transfer to what would normally be the entry 
point for the function, and produce random results if the array were not 
compiled function. 

Similarly, if putd is given a dotted pair of the form (number . address) where 
number is 0, 1, 2, or 3, and address falls in the subr range, putd assumes it 
is a subr and stores it away as described earlier, getd would then return cons 
of the left and right half, i.e., a dotted pair equal (but not eg) to the 
expression originally given putd . Similarly, a call to this function would 
transfer to the corresponding address. 

Finally, if putd is given any other list, it simply stores it away. A call to 
this function would then go through the interpreter as described in the 
appendix. 



8.2 



Mote that putd does not actually check to see if the s-expression is valid 
definition, i.e., begins with LAMBDA or NLAMBDA. Similarly, exprp is true if a 
definition is a list and not of the form (number . address), number o 
0, I, 2, or 3 and address a subr address; subrp is true if it is of this form. 
arglist and nargs work correspondingly. 

Only fn typ and argtype check function definitions further than that described 
above: both argtype and fntyp return NIL when exprp is true but car of the 
definition is not LAMBDA or NLAMBDA. 2 In other words, if the user uses putd to 
put (A B C) in a function definition cell, getd will return this value, the 
editor and prettyprint will both treat it as a definition, exprp will return T, 
ccodep and subrp NIL, arglist B, and nargs i . 

getd[x] get s the function definition of x. Value is the 

definition. 5 Value is NIL if x is not a literal 
atom, or has no definition. 

fgetd[x] fast version of getd that compiles open. 

Interpreted, generates an error, BAD ARGUMENT - 
F6ETD, if x is not a literal atom.^ 



These functions have different value on LAMBDAS and NLAMBDAs and hence must 
check. The compiler and interpreter also take different actions for 
LAMBDAs and NLAMBDAs, and therefore generate errors if the definition is 
neither. 



Note that in INTERLISP- 10 , getd of a subr performs a cons , as described on 
page 8.2. See footnote on fgetd below. 



Fgetd is intended primarily to check whether a function has a definition, 

rather than to obtain the definition. Therefore, for subrs, fgetd returns 

just the address of the function definition, not the dotted pair returned 
by getd , page 8.2, thereby saving the cons . 
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putd[x;y] put s the definition j; into x's function cell. 

Value is jr. Generates an error, ILLEGAL ARG - 
PUTD, if x is not a literal atom, or £ is a 
string, number, or literal atom other than NIL . 

putdq[x;y] n lambda version of putd; both arguments are 

considered quoted. Value is x. 

movd[ f rom;to;copyflg] Moves the definition of from to to, i.e., 

redefines to. If copyf lg =T, a copy of the 
definition of from is used. copyf Ig sT is only 
meaningful for exprs, although movd works for 
compiled functions and subrs as well. The value 
of movd is to. 

Notei fntirp , subrp , ccodep , exprp , argtype , nargs . and arglist all can be given 
either the name of a function, or a definition. 

fntyp[fn] Value is NIL if fn is not a function definition or 

the name of a defined function. Otherwise fntyp 
returns one of the following as defined in the 
section on function types: 



EXPR 


CEXPR 


SUBR 


FEXPR 


CFEXPR 


FSU8R 


EXPR* 


CEXPR* 


SUBR* 


FEXPR* 


CFEXPR* 


FSUBR* 



The prefix F indicates unevaluated arguments, the 
prefix C indicates compiled code, and the suffix * 
indicates an indefinite number of arguments. 
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fntyp returns FUNARG if fn is a funarg expression. 
See Section 11. 

is true if and only if fntyp[fn] is either 5UBR, 
FSUBR, SUBR*, or FSUBR*, i.e., the third column of 
fntyp' s. 

is true if and only if fntyp[fn] is either CEXPR, 
CFEXPR, CEXPR*, or CFEXPR*, i.e., second column of 
fntyp's. 

is true if fntyp[fn] is either EXPR, FEXPR, EXPR*, 
or FEXPR*, i.e. , first column of fntyp's. 
However, exprp[fn] is also true if fn is (has) a 
list definition that is not a SUBR, but does not 
begin with either LAMBDA or NLAHBDA. In other 
words, exprp is not quite as selective as fntyp . 

fn is the name of a function or its definition. 
The value of argtype is the argtype of fn, i.e., 

0, 1, 2, or 3, or NIL if fn is not a function. 
The interpretation of the argtype is: 

0 eval/spread function 

(EXPR, CEXPR, SUBR) 

1 no-eval/spread functions 

(FEXPR, CFEXPR, FSUBR) 

2 eval/nospread functions 

(EXPR®, CEXPR*, SUBR*) 

3 no-eval/nospread functions 

(FEXPR*, CFEXPR*, FSUBR*) 

1. e. » argtype corresponds to the rows of fntyps . 
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nargsCfn] value is the number of arguments of fn, or NIL if 

fn is not a function. 6 nargs uses exprp , not 
fntyp, so that nargs[(A (B C) D)]»2. If fn is a 
nospread function, the value of nargs is i. 

arglist[fn] value is the 'argument list 1 for fn. Note that 

the 'argument list' is an atom for nospread 
functions. Since NIL is a possible value for 
arglist . an error is generated, 
ARCS NOT AVAILABLE, if fn is not a function. 0 

If fn is a SUBR or FSUBR, the value of arglist is (U), (U V), (U V W), etc. 
depending on the number of arguments, if a SUBR** or FSUBR* , the value is U. 
This is merely a 'feature' of arglist , subrs do not actually store the names of 
their arguments(s) on the stack. However, if the user breaks or traces a SUBR 
(Section 15), these will be the argument names used when an equivalent EXPR 
definition is constructed. 



define[x] The argument of define is a list. Each element of 

the list is itself a list either of the form (name 
definition) or (name arguments ...). In the 
second case, following 'arguments' is the body of 
the definition. As an example, consider the 
following two equivalent expressions for defining 
the function null . 
1) (NULL (LAMBDA (X) (EQ X NIL))) 
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i.e., if exprp , ccodep , and subrp are all NIL. 

If fn is a compiled function, the argument list is constructed, i.e. each 
call to arglist requires making a new list. For interpreted functions, the 
argument list is simply cadr of getd . 
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2) (NULL (X) (EO X NIL) ) 



def ine will generate an error on encountering an atom where a defining list is 
expected. If dfnf lg =NIL, an attempt to redefine a function fn will cause 
def ine to print the message (fn REDEFINED) and to save the old definition of fn 
using savedef before redefining it. If dfnf Ig sT, the function is simply 
redefined. If dfnf lg gpROP or ALLPROP, the new definition is stored on the 
property list under the property EXPR. (ALLPROP affects the operation of rpaqq 
and rpag , section 5). dfnf Ig is initially NIL, 

dfnf Ig is reset by load to enable various ways of handling the defining of 
functions and setting of variables when loading a file. For most applications, 
the user will not reset dfnf Ig directly himself. 

Mote: define will operate correctly if the function is already defined and 
broken . advised , or broken-in . 

def ineq[x^ ; . . . ;x n 3 nlambda nospread version of def ine , i.e., takes an 

indefinite number of arguments which are not 
evaluated. Each x 4 must be a list, of the form 
described in define . def ineg calls define , so 
dfnf Ig affects its operation the same as def ine . 

savedef [fn] Saves the definition of fn on its property list 

under property EXPR, CODE, or SUBR depending on 
* ts fntyp . Value is the property name used. If 
getd[fn] is non-NIL, but fntyp[fn] is NIL, saves 
on property name LIST. This situation can arise 
when a function is redefined which was originally 
defined with LAHBDA misspelled or omitted. 
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If fn is a list, savedef operates on each function 
in the list, and its value is a list of the 
individual values. 

Restores the definition of fn from its property 
list under property prop (see savedef above). 
Value is prop . If nothing saved under prop , and 
fn is defined, returns (prop NOT FOUND), otherwise 
generates an error, NOT A FUNCTION. 

If prop is not given, i.e. NIL, unsavedef looks 
under EXPR, CODE, and SUBR, in that order. Tho 
value of unsavedef is the property name, or if 
nothing is found and fn is a function, the value 
is (NOTHING FOUND) ; otherwise generates an error, 
NOT A FUNCTION. 

If dfnflg sNIL, the current definition of fn, if 
any, is saved using savedef . Thus one can use 
unsavedef to switch back and forth between two 
definitions of the same function, keeping one on 
its property list and the other in the function 
definition cell. 

If fn is a list, unsavedef operates on each 
function of the list, and its value is a list of 
the individual values. 
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eval[xr eval evaluates the expression x and returns this 

value i.Q. eval provides a way of calling tho 
interpreter. Not© that eval is itself a lambda 
type function, so its argument is first evaluated, 



e.g. , 



o-SET(F00 (ADD1 3)) 
(A0D1 3) 
«-(EVAL F00) 
4 

••EVAL(FOO) or (EVAL (QUOTE F00)) 
(ADD1 3) 



e[x] nlambda nospread version of eval . Thus it 

eliminates the extra pair of parentheses for the 
list of arguments for eval . i.e., e x is 
equivalent to evaltx]. Note however that in 
INTERLISP, the user can type just x to get x 
evaluated. (See Section 3.) 

apply[ fn ;args] apply applies the function fn to the arguments 

args . The individual elements of args are not 
evaluated by apply , fn is simply called with args 
as its argument list. 5 Thus for the purposes of 
apply , nlambda f s and lambda 's are treated the 
same. However like eval , apply is a lambda 
function so its arguments are evaluated before it 
is called e.g., 



eval is a subr so that the 'name' x does not actually appear on the stack. 

8 

Note that fn may still explicitly evaluate one or more of its arguments 
itself, as in the case of setq . Thus 

(APPLY (QUOTE SETQ) (QUOTE (F00 (ADD1 3)))) will set FOO to 4, whereas 
(APPLY (QUOTE SET) (QUOTE (FOO (ADD1 3)))) will set FOO to the expression 
(AD01 3). 
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-SET(F001 3) 
3 

«-SET(F002 4) 
4 

«■( APPLY (QUOTE IPLUS) (LIST FOOl F002] 
7 



Here, fool and foo2 were evaluated when the second 
argument to apply was evaluated. Compare with: 



-SET (FOOl (ADD1 2)) 
(ADD1 2) 

-SET(F002 (SUBi 5)) 
(SUB1 5) 

-(APPLY (QUOTE IPLUS) (LIST FOOl F002] 

NON-NUMERIC ARG 
(ADD1 2) 



apply^E fn;arg 1 ; . . . ;arg n J equivalent to applyCfnjlisttarg^ ; . . . ;arg n ]] For 

example, if fn is the name of a functional 
argument to be applied to x and one can write 
( APPLY® FN X Y), which is equivalent to 
(APPLY FN (LIST X Y)). Note that (FN X Y) 
specifies a call to the function FN itself, and 
will cause an error if FN is not defined. (See 
Section .16.) FN will not be evaluated. 

evala[x;a] Simulates a-list evaluation as in LISP 1.5. x is a 

form, a is e list of dotted pairs of variable name 
and value, a is 'spread 1 on the stack, and then x 
is evaluated, i.e., any variables appearing free 
in x, that also appears as car of an element of a 
will be given the value in the cdr of that 
element. 

rpt[rptn ;rptf ] Evaluates the expression rptf rptn times . At any 

point, rptn is the number -of evaluations yet to 
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take place. Returns the value of the last 
evaluation. If rptn < 0, rptf is not evaluated, 
and the value of rj)t is NIL. 



Mote: rpt is a lambda function, so both its arguments are evaluated before rpt 
is called. For most applications ♦ the user will probably want to use 



rptq[ rptn ;rptf ] n lambda version of rjgt: rptn is evaluated, rptf is 

not, e.g. (RPTQ 10 (READ) ) will perform ten calls 
to read , rptq compiles open. 

arg[var;m] Used to access the individual arguments of a 

lambda nospread function. arg is an n lambda 
function used like set. var is the name of the 
atomic argument list to a lambda-nospread 
function, and is not evaluated ; m is the number of 
the desired argument, and is evaluated. For 
example, consider the following definition of 
iplus in terms of plus . 



[LAMBDA X 
(PROG ((MO) 
(N 0)) 
LP (COND 

((EO U X) 

(RETURN M) ) ) 
(SETQ N (ADD1 N)) 
[SETQ M (PLUS H (ARG X N) ) ) 
(GO LP] 



The value of arg is undefined for m less than or 
equal to 0 or greater than the value of var 
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For lambda nospread functions, the lambda variable is bound to the number 
of arguments actually given to the function. See Section 4. 
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Lower numbered arguments appear earlier in the 
form, e.g. for (IPLUS A B C), 
arg[X;i]sthe value of A, 
arg[X;2]nhe value of B, and 
arg[X|3]sthe value of C. 

Not® that the lambda variable should never be 
reset. However > individual arguments can be reset 
using setarg described below. 

sets to x the mth argument for the lambda nospread 
function whose argument list is var . var is 
considered quoted, m and x are evaluated; e.g. in 
the previous example, (SETAR6 X (ADD! N)(MINUS M ) ) 
would be an example of the correct form for 
setarg. 
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SECTION 9 
THE INTERLISP EDITOR 



The INTERLISP editor allows rapid, convenient modification of list structures . 
Most often it is used to edit function definitions, (often while the function 
itself is running) via the function editf , e.g., EDITF(FOO). However, the 
editor can also be used to edit the value of a variable, via editv , to edit a 
property list, via editp , or to edit an arbitrary expression, via edite. It is 
an important feature which allows good on-line interaction in the IWTERLISP 
system/ 

This chapter begins with a lengthy introduction intended for the new user. The 
reference portion begins on page 9.15. 

9.1 Introduction 

Let us introduce some of the basic editor commands, and give a flavor for the 
editor's language structure by guiding the reader through a hypothetical 
editing session. Suppose we are editing the following incorrect definition of 
append : 



The editor was written by and is the responsibility of W. Teitelman. 



[LAMBDA (X) 

y 

(com 

( (NUL X) 
Z) 

(T (CONS (CAR) 

(APPEND (CDR X Y] 



We call the editor via the function editf: 



*-EDXTF( APPEND) 
EDIT 



The editor responds by typing EDIT followed by *, which is the editor's prompt 

p 

character, i.e., it signifies that the editor is ready to accept commands. 



At any given moment, the editor's attention is centered on some substructure of 
the expression being edited. This substructure is called the current 
expression , and it is what the user sees when he gives the editor the command 
P, for print. Initially, the current expression is the top level one, i.e., 
the entire expression being edited. Thus: 

«p 

(LAMBDA (X) Y (COND & &)) 

Note that the editor prints the current expression as though printlevel were 
set to 2, i.e., sublists of sublists are printed as &. The command ? will 
print the current expression as though printlevel were 1000. 

*? 

(LAMBDA (X) Y (COND ((NUL X) Z) (T (CONS (CAR) (APPEND (CDR X Y)))))) 
and the command PP will prettyprint the current expression* 



In other words, all lines beginning with * were typed by the user, the rest 
by the editor. 
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A positive integer is interpreted by the editor as a command to descend into 
the correspondingly numbered element of the current expression. Thus: 



»2 
& p 

(X) 



A negative integer has a similar effect, but counting begins from the end of 
the current expression and proceeds backward, i.e., -1 refers to the last 
element in the current expression, -2 the next to the last, etc. For either 
positive integer or negative integer, if there is no such element, an error 
occurs, the editor types the faulty command followed by a ?, and then another 
*. The current expression is never changed when a command causes an error. 
Thus : 

a p 
(X) 

2 ? 
«j 

*p 
X 



A phrase oj the form 9 the current expression is changed' or 9 the current 
expression becomes 9 refers to a shift in the editor's attention . not to a 
modification of the structure being edited . 



When the user changes the current expression by descending into it, the old 
current expression is not lost. Instead, the editor actually operates by 



'Editor errors 1 are not of the flavor described in Section 16, i.e., they 
never cause breaks or even go through the error machinery but are direct 
calls to error ! indicating that a command is in some way faulty. What 
happens next depends on the context in which the command was being 
executed. For example, there are conditional commands which branch on 
errors. In most situations, though, an error will cause the editor to type 
the faulty command followed by a ? and wait for more input. Note that 
typing control-E while a command is being executed aborts the command 
exactly as though it had caused an error. 
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maintaining a chain of expressions leading to the current one. The current 
expression is simply the last link in the chain. Descending adds the indicated 
subexpression onto the end of the chain, thereby making it be the current 
expression. The command 0 is used to ascend the chain; it removes the last 
link of the chain, thereby making the previous link be the current expression. 
Thus: 

ftp 
X 

*0 P 
(X) 

*0 -1 P 

(COND (& Z) (T &)) 

A 

Mote the use of several commands on a single line in the previous output. The 
editor operates in a line buffered mode, the same as evalqt . Thus no command 
is actually seen by the editor, or executed, until the line is terminated, 
either by a carriage return, or a matching right parenthesis. The user can 
thus use control-A and control-Q for line-editing edit commands, the same as he 
does for inputs to evalqt . 

In our editing session, we will make the following corrections to append : 
delete Y from where it appears, add Y to the end of the argument list,^ change 
NUL to NULL , change Z to Y, add Z after CAR, and insert a right parenthesis 
following CDR X. 

First we will delete Y. By now we have forgotten where we are in the function 
definition, but we want to be at the "top" so we use the command t, which 
ascends through the entire chain of expressions to the top level expression, 



These two operations could be though of as one operation, i.e., MOVE Y from 
its current position to a new position, and in fact there is a MOVE command 
in the editor. However, for the purposes of this introduction, we will 
confine ourselves to the simpler edit commands. 
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which then becomes the current expression, i.e., t removes all links except the 
first one. 

*t P 

(LAMBDA (X) Y (COND & &)) 

u 

Note that if we are already at the top, t has no effect, i.e., it is a NOP. 
However, 0 would generate an error. In other words, t means "go to the top," 
while 0 means "ascend one link." 

The basic structure modification commands in the editor are: 

(n) n > 1 deletes the corresponding 

element from the current expression. 

n,m > 1 replaces the nth element in the current 
expression with 

i m 

n,m > 1 inserts e« ... e m before the nth element 
— i m — 

in the current expression. 
Thus: 

«P 

( LAMBDA (X) Y (COND & &)) 
*(3) 

*<2 (X Y)) 
ap 

(LAMBDA (X Y) (COND & &)) 

A 

All structure modification done by the editor is destructive, i.e.. the editor 
uses rplaca and rplacd to physically change the structure it was given. 

Note that all three of the above commands perform their operation with respect 



(n e t ... e m ) 



<-n ej ... e m ) 
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to the nth element from the front of the current expression; the sign of n is 
used to specify whether the operation is replacement or insertion. Thus, there 
is no way to specify deletion or replacement of the nth element from the end of 
the current expression/ or insertion before the nth element from the end 
without counting out that element *s position from the front of the list. 
Similarly, because we cannot specify insertion after a particular element, we 
cannot attach something at the end of the current expression using the above 
commands . Instead, we use the command N (for nconc ) . Thus we could have 
performed the above changes instead by: 



( LAMBDA (X) Y (COND & &)) 

*(3) 

*2 (N Y) 
ap 

(X Y) 
ftf P 

* (LAMBDA (X Y) (COND & &)) 



Mow we are ready to change NUL to NULL. Rather than specify the sequence of 
descent commands necessary to reach NUL, and then replace it with NULL, e.g. , 3 
2 1 (1 NULL), we will use F, the find command, to find NUL: 



ftp 

(LAMBDA (X Y) (COND & &)) 

*F NUL 
*P 

(NUL X) 
*(1 NULL) 
*0 P 

( (NULL X) Z) 



Mote that F is special in that it corresponds to two inputs. In other words, F 
says to the editor, "treat your next command as an expression to be searched 
for." The search is carried out in printout order in the current expression. 
If the target expression is not found there, F automatically ascends and 
searches those portions of the higher expressions that would appear after (in a 
printout) the current expression. If the search is successful, the new current 
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expression will be the structure where the expression was found, and the chain 
will be the same as one resulting from the appropriate sequence of ascent and 
descent commands. If the search is not successful, an error occurs, and 
neither the current expression nor the chain is changed: 

up 

((NULL X) Z) 
*F COND P 

COND ? 

*( (NULL X) Z) 

ft 

Here the search failed to find a cond following the current expression, 
although of course a cond does appear earlier in the structure. This last 
example illustrates another facet of the error recovery mechanism: to avoid 
further confusion when an error occurs, all commands on the line beyond the one 
which caused the error (and all commands that may have been typed ahead while 
the editor was computing) are forgotten.^ 

We could also have used the R command (for replace) to change NUL to NULL . A 
command of the form (R & z ) will replace all occurrences of e^ in the current 
expression by e^. There must be at least one such occurrence or the R command 
will generate an error* Let us use the R command to change all Z's (even 
though there is only one) in append to Y: 



If the search is for an atom, e.g., F NUL, the current expression will be 
the structure containing the atom. 

F is never a NOP, i.e., if successful, the current expression after the 
search will never be the same as the current expression before the search. 
Thus F expr repeated without intervening commands that change the edit 
chain can be used to find successive instances of expr . 



i.e. the input buffer is cleared (and saved) (see clearbuf , Section 14). 
It can be restored, and the type-ahead recovered via the command SBUFS 
(alt-mode BUFS), described in Section 22. 
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*t (R Z Y) 
*F 2 

Z ? 
*PP 

[LAMBDA (X Y) 
(COND 

( (NULL X) 
Y) 

(T (CONS (CAR) 

(APPENO (COR X Y] 

The next task is to change (CAR) to (CAR X). We could do this by 
(R (CAR) (CAR X)), or by: 

»F CAR 
*(N X) 
*P 

(CAR X) 
« 

The expression we now want to change is the next expression after the current 
expression, i.e., we are currently looking at (CAR X) in (CONS (CAR X) (APPEND 
(CDR X Y))). We could get to the append expression by typing 0 and then 3 or 
-1, or we can use the command NX, which does both operations: 

*P 

(CAR X) 
*NX P 

(APPEND (CDR X Y)) 
* 

Finally, to change (APPEND (CDR X Y)) to (APPEND (CDR X) V), we could perform 
(2 (CDR X) Y), or (2 (CDR X)) and (N Y), or 2 and (3), deleting the Y, and then 
0 (N Y). However, if Y were a complex expression, we would not want to have to 
retype it. Instead, we could use a command which effectively inserts and/or 
removes left and right parentheses. There are six of these commands: 
BI,BO,LI,LO,RI, and RO, for both in, both out, left in, left out, right in, and 
right out. Of course, we will always have the same number of left parentheses 
as right parentheses, because the parentheses are just a notational guide to 
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structure that is provided by our print program. Thus, left in, left out, 
right in, and right out actually do not insert or remove just one parenthesis, 
but this is very suggestive of what actually happens. 



In this case, we would like a right parenthesis to appear following X in (CDR X 
Y). Therefore, we use the command (RI 2 2), which means insert a right 
parentheses after the second element in the second element (of the current 
expression ) : 



a p 

(APPEND (CDR X Y)) 
*(RI 2 2) 
* p 

(APPEND (CDR X) Y) 



We have now finished our editing, and can exit from the editor, to test append , 
or we could test it while still inside of the editor, by using the E command: 



*E APPEND( (A B) (C D E)) 
(A B C D E) 



■ 

The E command causes the next input to be given to evalqt . If there is another 
input following it, as in the above example, the first will be applied ( apply ) 
to the second. Otherwise, the input is evaluated (eval). 



We prettyprint append , and leave the editor. 



Herein lies one of the principal advantages of a LISP oriented editor over ] 
a text editor: unbalanced parentheses errors are not possible. 
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*pp 

[LAMBDA (XV) 
(COND 

((NULL X) 
Y) 

(T (CONS (CAR X) 

(APPEND (CDR X) Y] 

APPEND 

9.2 Commands for the New User 

As mentioned earlier, the INTERLISP manual is intended primarily as a reference 
manual, and the remainder of this chapter is organized and presented 
accordingly, ' While the commands introduced in the previous scenario constitute 
a complete set, i.e., the user could perform any and all editing operations 
using just those commands, there are many situations in which knowing the right 
command(s) can save the user considerable effort* We include here as part of 
the introduction a list of those commands which are not only frequently 
applicable but also easy to use. They are not presented in any particular 
order, and are all discussed in detail in the reference portion of the chapter. 

UNDO undoes the last modification to the structure 

being edited, e.g., if the user deletes the wrong 
element, UNDO will restore it. The availability 
of UNDO should give the user confidence to 
experiment with any and all editing commands, no 
matter how complex, because he can always reverse 
the effect of the command. 

BK like NX, except makes the expression immediately 

before the current expression become current. 

BF backwards find. Like F, except searches 

backwards, i.e. » in inverse print order. 
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Restores the current expression to the expression 
before the last "big jump", e.g., a find coram ami , 
an or another \. For example, if the usor 
types F CQND, and then "F CAR, \ would take him 
back to the COND. Another \ would take him back to 
the CAR. 

\P like \ except it restores the edit chain to its 

state as of the last print, either by P, ?, or PP. 
If the edit chain has not been changed since the 
last print, \P restores it to its state as of tho 
printing before that one, i.e., two chains are 
always saved. 

Thus if the user types P followed by 3 2 1 P, \P will take him back to the 
first P, i.e., would be equivalent to 0 0 0. Another \P would then take him 
back to the second P. Thus the user can use \P to flip back and forth between 
two current expressions. 

The search expression given to the F or BF command 
need not be a literal S-expression . Instead, it 
can be a pattern. The symbol & can be used 
anywhere within this pattern to match with any 
single element of a list, and can be used to 
match with any segment of a list. Thus, in tho 
incorrect definition of append used earlier, 
F (NUL &) could have been used to find (NUL X), 
and F( CDR --) or F (CDR & but not F (CDR 
to find (CDR H), 

Note that & and can be nested arbitrarily deeply in the pattern. For 
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example, if there are many places where the variable X is set, F SETQ may not 
find the desired expression, nor may F (SETQ X &). It may be necessary to use 
F (SETQ X (LIST --)). However, the usual technique in such a case is to pick 
out a unique atom which occurs prior to the desired expression, and perform two 
F commands. This "homing in" process seems to be more convenient than ultra- 
precise specification of the pattern, 

$ (alt-mode) $ is equivalent to --.at the character level, e.g. 

VERS will match with VERYLONGATOM, as will SATOM, 
SLONGS, (but not SLONG) and SVSNSMS. $ can be 
nested inside of a pattern, e.g., 

F (SETQ VERS (CONS >-)). 

If the search is successful, the editor will print 

= followed by the atom which matched with the S- 

atom, e *g . i 

*F (SETQ VERS &) 
—VERYLONGATOM 

A 

Frequently the user will want to replace the entire current expression, or 
insert something before it. In. order to do this using a command of the form (n 
e l • e m ) or (-n ej ... e m ), the user must be above the current expression. 
In other words, he would have to perform a 0 followed by a command with tho 
appropriate number. However, if he has reached the current expression via an F 
command, he may not know what that number is. In this case, the user would 
like a command whose effect would be to modify the edit chain so that the 
current expression became the first element in a new, higher current 
expression. Then he could perform the desired operation via (1 . .. e m ) or 
(-1 e t ... e ). UP is provided for this purpose. 
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UP after UP operates, the old current expression is 

the first element of the new current expression. 
Note that if the current expression happens to bo 
the first element in the next higher expression, 
then UP is exactly the same as 0. Otherwise, UP 
modifies the edit chain so that the new current 
expression is a tail 9 of the next higher 
expression: 

*F APPEND P 
(APPEND (CDR X) Y) 
*UP P 

. . . (APPEND & Y) ) 

»0 P 

(CONS (CAR X) (APPEND & Y)) 

a 

The ... is used by the editor to indicate that the 
current expression is a tail of the next higher 
expression as opposed to being an element (i.e., a 
member) of the next higher expression. Note: if 
the current expression is already a tail, UP has 
no effect. 

(B ... e m ) inserts e^ ... e m before the current expression, 

i.e., does an UP and then a -i. 

(A 6| ... e m ) inserts ... e m after the current expression, 

i.e., does an UP and then either a (-2 Gj ... e m ) 
or an (N 6| ... © m h if the current expression is 
the last one in the next higher expression. 



9 Throughout this chapter 'tail 1 means 'proper tail 1 (see Section 5). 
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replaces current expression by -e^ ... e m , i.e., 
does an UP and then a (1 e t ... e m ). 

DELETE deletes current expressions equivalent to ( :). 

Earlier, we introduced the RI command in the append example. The rest of the 
commands in this family: BI, BO, LI, LO, and RO, perform similar functions and 
are useful in certain situations. In addition, the commands MBD and XTR can be 
used to combine the effects of several commands of the BX-BO family. MBD is 
used to embed the current expression in a larger expression. For example, if 
the current expression is (PRINT bigexpression), and the user wants to replace 
it by (COND (FIG (PRINT bigexpression))), he could accomplish this by (LI 1), 
(-1 FLG), (LI 1), and (-1 COND), or by a single MBD command, page 9.47. 

XTR is used to e xtr act an expression from the current expression. For example, 
extracting the PRINT expression from the - above. COND .could be accomplished by 
(1), (LO 1), (1), and (LO 1) or by a single XTR command. The new user is 
encouraged to include XTR and MBD in his repertoire as soon as he is familiar 
with the more basic commands/ 

This ends the introductory material. 



(: e % ... e m ) 
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9.3 Attention Changing Commands 



Commands to the editor fall into three classes: commands that change the 
current expression (i.e., change the edit chain) thereby "shifting the editor's 
attention," commands that modify the structure being edited, and miscellaneous 
commands, e.g., exiting from the editor, printing, evaluating expressions, etc. 

Within the context of commands that shift the editor's attention, we can 
distinguish among (1) those commands whose operation depends only on the 
structure of the edit chain, e.g., 0, UP, NX; (2) those which depend on the 
contents of the structure, i.e., commands that search; and (3) those commands 
which simply restore the edit chain to some previous state, e.g., \, \P. (1) 
and (2) can also be thought of as local, small steps versus open ended, big 
jumps. Commands of type (!) are discussed on page 9.15~21 ? type (2) on pago 
9.21-34, and type (3) on page 9.34-36. 



9.3.1 Local Attention-Changing Commands 

UP (1) If a P command would cause the editor to type 

... before typing the current expression, i.e. the 
current expression is a tail of the next higher 
expression, UP has no effect; otherwise 
(2) UP modifies the edit chain so that the old 
current expression (i.e., the one at the time UP 
was called) is the first element in the new 
current expression.^ 



If the current expression is the first element in the next highor 
expression UP simply does a 0. Otherwise UP adds the corresponding tail to 
the edit chain. 
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Examples: The current expression in each case is 
(COND ((NULL X) (RETURN Y))). 



COND 
*UP P 

(COND (& &)) 

2 . ' 1 P 

( (NULL X) (RETURN Y)) 
®UP P 

. . . ((NULL X) (RETURN Y) ) 
a UP P 

.... . ( (NULL X) (RETURN Y))> 

3. *F NULL P 
(NULL X) 
&UP P 

((NULL X) (RETURN Y)) 
®UP P 

... ( (NULL X) (RETURN Y))) 



The execution of UP is straightforward, except in those cases where the current 
expression appears more than once in the next higher expression. For example, 
if the current expression is (A NIL B NIL C NIL) and the user performs 4 
followed by UP, the current expression should then be . . . NIL C NIL). UP can 
determine which tail is the correct one because the commands that descend save 
the last tail on an internal editor variable, lastail . Thus after the 4 
command is executed, lastail is (NIL C NIL). When UP is called, it first 
determines if the current expression is a tall of the next higher expression. 
If it is, UP is finished. Otherwise, UP computes 

memb[ cu rrent- express ion ; next-higher-express ion] to obtain a tail beginning with 
the current expression.** If there are no other instances of the current 
expression in the next higher expression, this tail is the correct one. 



The current expression should always be either a tail or an element of the 
next higher expression. If it is neither, for example the user has 
directly (and incorrectly) manipulated the edit chain, UP generates an 
error. 
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IP 

Otherwise UP uses lastail to select the correct tail. 



n (n > 1) adds the nth element of the current expression to 

the front of the edit chain, thereby making it be 
the new current . expression . Sets lastai 1 for use 
by UP. Generates an error if the current 
expression is not a list that contains at least n 
elements. 

- n ( n > I ) adds the nth element from the end of the current 

expression to the front of the edit chain, thereby 
making it be the new current expression. Sets 
lastail for use by UP. Generates an error if the 
current expression is not a list that contains at 
least n elements. 

0 Sets edit chain to cdr of edit chain, thereby 

making the next higher expression be the new 
current expression. Generates an error if there 
is no higher expression, i.e. cdr of edit chain is 
NIL. 

Note that 0 usually corresponds to going back to the next higher left 
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Occasionally the user can get the edit chain into a state where las tai l 
cannot resolve the ambiguity, for example if there were two non-atomic 
structures in the same expression that were cmj, and the user descended more 
than one level into one of them and then tried to come back out using UP. 
In this case, UP prints LOCATION UNCERTAIN and generates an error. Of 
course, we could have solved this problem completely in our implementation 
by saving at each descent both elements and tails. However, this would bo 
a costly solution to a situation that arises infrequently, and when it 
does, has no detrimental effects. The lastail solution is cheap and 
resolves 99% of the ambiguities. 
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parenthesis, but not always. For example, if the current expression is 
(A BCD E F B), and the user performs: 



«3 UP P 

. . . C D E F 6) 

*3 UP P 

... E F G) 

*0 P 

... C D E F G) 



If the intention is to go back to the next higher left parenthesis, regardless 

i 3 

of any intervening tails, the command !0 can be used. 



10 does repeated O's until it reaches a point where 

the current expression is not a tail of the next 

higher expression, i.e., always goes back to tho 
next higher left parenthesis. 



t sets edit chain to last of edit chain, thereby 

making the top level expression be the current 
expression. Never generates an error. 

NX effectively does an UP followed by a 2,*** thereby 

making the current expression be the next 
expression. Generates an error if the current 
expression is the last one in a list. (However, 
!NX described below will handle this case.) 

BK makes the current expression be the previous 
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!0 is pronounced bang-2ero. 

Both NX and BK operate by performing a !0 followed by an appropriate 
number, i.e. there won't be an extra tail above the new current expression, 
as there would be if NX operated by performing an UP followed by a 2. 
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expression in the next higher expression. 
Generates an error if the current expression is 
the first expression in a list. 



For example, if the current expression is (COND ((NULL X) (RETURN Y) ) ) 



*F RETURN P 
(RETURN Y) 
*BK P 
(NULL X) 



(NX n) n > 1 



equivalent to n NX commands, except if an error 
occurs, the edit chain is not changed. 



(BK n) n > I 



equivalent to n BK commands/ except if an error 
occurs, the edit chain is not changed. 



Note: (NX ~n ) is equivalent to (BK n), and vice versa. 



NX 



makes current expression be the next expression at 
a higher level, i.e., goes through any number of 
right parentheses to get to the next expression. 
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For example: 



*PP 

(PROG ((L I) 

(UF L) ) 
LP (COND 

( (NULL (SETO L (CDR L) ) ) 

(ERROR!)) 
([NULL (CDR (FMEMB (CAR L) 

(CADR L] 

(GO LP))) 
(EDITCOM (QUOTE NX)) 
(SETQ UNFINO UF) 
(RETURN D) 

*F CDR P 
(CDR L) 
"NX 

NX ? 
*!NX P 
(ERROR!) 
*!NX P 

((NULL &) (GO LP)) 
*!NX P 

(EDITCOM (QUOTE NX) ) 

ft 



!NX operates by doing O's until it reaches a stage where the current expression 
is not the last expression in the next higher expression, and then does a NX. 
Thus !NX always goes through at least one unmatched right parenthesis, and the 
new current expression is always on a different level, i.e., !NX and NX always 
produce different results. For example using the previous current expression: 



»F CAR P 
(CAR L) 
*!NX P 
(GO LP) 
*\P P 
(CAR L) 
"NX P 
(CADR L) 



(NTH n) n * .0 equivalent to n followed by UP, i.e., causes tho 

list starting with the nth element of the current 
expression (or nth from the end if n < 0) to 
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become the current expression. ° Causes an error 
if current expression does not have at least n 
elements. 

A generalised form of NTH using location specifications is described on page 
9.32. 



9.3.2 Commands That Search 

All of the editor commands that search use the same pattern matching routine. 
We will therefore begin our discussion of searching by describing the pattern 
match mechanism. A pattern pat matches with x if: 



6a. 



pat is eq to x. 
pat is &. 

pat is a number and eqp to x. 

pat is a string and strequal[pat ;x] is true. 

If cartpat] is the atom *ANY«, cdr[pat] is a list of patterns and 
pat matches x if and only if one of the patterns on cdr[pat] 
matches x. 

If pat is a literal atom or string containing one or more alt- 
modes, each $ can match an indefinite number (including 0) of 
contiguous characters in a literal atom or string, e.g. 
VERS matches both VERYLONGATOM and 
"VERYLONGSTRING" as do SLONGS (but not 
SLONG), and SVSLSTS. 



15 
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(NTH 1) is a NOP, as is (NTH -n) where n is the length of the current 
expression . 

This routine is available to the user directly, and is described on page 
9.89. 
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6b o If gat is a literal atom or string ending in two alt-modes, pat 
matches with the first atom or string that is "close" to pat , in 
the sense used by the spelling corrector (Section 17). E.g. 
CONSSSS matches with CONS, CNONCSS with NCONC or NCONC1. 
The pattern matching routine always types a message of the form 
s.x to inform the user of the object matched by a pattern of type 
6a or 6b, 17 e.g. «VERYL0N6AT0M. 

7. If car[pat] is the atom pat matches x if 

a. cdr[ pat JsNIL, i.e. fiats (--), e.g. 

(A —) matches (A) (A B C) and (A . B) 

In other words, can match any tail of a list. 

b. cdr[pat] matches with some tail of x, 

e.g. (A (&)) will match with (ABC (D)) p 
but not (ABC D), or (A B C (D) E). However, 
note that (A. ---'(&) --) will match with 
(A B C (D) E). 

In other words, can match any interior segment of a list . 

8. If car[pat] is the atom ss, gat matches x if and only if cdr[pat] 
is efl to \ J 8 

9. Otherwise if x is a list, gat matches x if car[pat] 
matches car[x], and cdr[pat] matches cdr[x]. 

V/hen the editor is searching, the pattern matching routine is called to match 

with elements in the structure, unless the pattern begins with in which 

case cdr of the pattern is matched against proper tails in the structure. Thus 
if the current expression is (A B C (B C)), 



unless editquietf lgsT. 

Pattern 8 is for use by programs that call the editor as a subroutine , 
since any non-atomic expression in a command typed in by the user obviously 
cannot be e^ to already existing structure. 
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*F (B --) 

*P (B C) 

ft 0 F (,., B -•) 

# p 

... B C (B C)) 

Matching is also attempted with atomic tails (except for NIL). Thus 
*P 

(A (B . C)) 

*F C 
*P 

... . C) 

Although the current expression is the atom C after the final command, it is 
printed as ... . C) to alert the user to the fact that C is a tail, not an 
element. Mote that the pattern C will match with either instance of C in 
(A C (B , C)), whereas (... . C) will match only the second C. The pattern NIL 
will only match with NIL as an element, i.e. it will not match in (A B), even 
though cddr of (A B) is NIL. However, (... . NIL) (or equivalently (...)) may 
be used to specify a NIL tail, e.g. (... . NIL) will match with cdr of the 
third subexpression of ((A . B) (C . D) (E) ) . 

Search Algorithm 

Searching begins with the current expression and proceeds in print order. 

Searching usually means find the next instance of this pattern, and 

consequently a match is not attempted that would leave the edit chain 
19 

unchanged. At each step, the pattern is matched against the next element in 
the expression currently being searched, unless the pattern begins with ... in 
which case it is matched against the next tail of the expression. 



However, there is a version of the find command which can succeed and leave 
the current expression unchanged (see page 9.26). 



9.23 



If the match is not successful, the search operation is recursive first in the 
car direction and then in the cdr direction, i.e., if the element undor 
examination is a list, the search descends into that list before attempting to 
match with other elements (or tails) at the same level.*" 

However, at no point is the total recursive depth of the search (sum of numbor 
of cars and cdrs descended into) allowed to exceed the value of the variable 
maxlevel . At that point, the search of that element or tail is abandoned, 
exactly as though the element or tail had been completely searched without 
finding a match, and the search continues with the element or tail for which 
the recursive depth is below maxlevel . This feature is designed to enable the 
user to search circular list structures (by setting maxlevel small), as woll as 
protecting him from accidentally encountering a circular list structure in the 
course of normal editing, maxlevel is initially set to 300. 21 

If a successful match is not found in the current expression, the search 
automatically ascends to the next higher expression, and continues searching 
there on the next expression after the expression it just finished searching. 
If there is none, it ascends again, etc. This process continues until the 
entire edit chain has been searched, at which point the search fails, and an 
error is generated. If the search fails (or, what is equivalent, is aborted by 
control-E), the edit chain is not changed (nor are any conses performed) . 

If the search is successful, i.e., an expression is found that the pattern 



on 

There is also a version of the find command (see page 9.27) which only 
attempts matches at the top level of the current expression, i.e., does not 
descend into elements, or ascend to higher expressions. 



21 
22 



maxlevel can also be set to NIL, which is equivalent to infinity. 
See footnote on page 9.24. 
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matches, the edit chain is set to the value it would have had had the usor 
reached that expression via a sequence of integer commands. 

If the expression that matched was a list, it will be the final link in the 
edit chain, i.e., the new current expression. If the expression that matched 
is not a list, e.g., is an atom, the current expression will be the tail 

beginning with that atom, 25 i.e., that atom will be the first element in the 

24 

new current expression. In other words, the search effectively does an UP. 



Search Commands 

All of the commands below set lastail for use by UP, set unf ind for use by \ 
(page 9.35), and do not change the edit chain or perform any conses if they 
are unsuccessful or aborted. 

F pattern i.e., two commands: the F informs the editor that 

the next command is to be interpreted as a 
pattern. This is the most common and useful form 
of the find command. If successful, the edit 
chain always changes, i.e., F pattern means find 
ths next instance of pattern . 



If memb[pattern;current-expression] is true, F 
does not proceed with a full recursive search. If 
the value of the memb is NIL, F invokes the search 
algorithm described earlier. 



23 

Unless the atom is a tail, e.g. B in (A . B). In this case, the current 
expression will be B, but will print as . . . . B). 

24 

Unless upf indf lg sNIL (initially set to T) . For discussion, see page 
9.43-44. 
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Thus if the current expression is 

(PROG NIL LP (COND (-- (GO LP1))) ... LP1 ..v). F LP1 will find the prog label, 
not the LP1 inside of the GO expression, even though the latter appears first 
(in print order) jtn the current expression. Note that i (making the atom PROG 
be the current expression)! followed by F LPl would find the first LP1. 

(F pattern N) same as F pattern, i.e., finds the next instance 

of pattern/except the memb check of F pattern is 
not performed. 

(F pattern T) Similar to F pattern, except may succeed without 

changing edit chain, and does not perform the monb 
check. 

Thus if the current expression is (COND ..), F COND will look for the next 
COND, but (F COND T) will 'stay here 1 . 

(F pattern n) n > 1 Finds the nth place that pattern matches. 

Equivalent to (F pattern T) followed by 
(F pattern N) repeated n-1 times. Each time 
pattern successfully matches, n is decremented by 
1, and the search continues, until n reaches 0. 
Note that the pattern does not have to match with 
n identical expressions; it just has to match n 
times. Thus if the current expression is 
(FOOl F002 F003), (F FOOS 3) will find F003 . 
If the pattern does not match successfully n 
times, an error is generated and the edit chain is 
unchanged (even if the pattern matched n-i times). 
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(F pattern) or only matches with elements at the 

(F pattern NIL) top level of the current expression, i.e., the 

search will not descend into the current 
expression, nor will it go outside of the current 
expression. May succeed without changing edit 
chain. 

For example, if the current expression is 

(PROG NIL (SETQ X (COND & &)) (COND 8.) . ..), F COND will find the COND inside 
the SETQ, whereas (F (COND --)) will find the top level COND, i.e., the second 
one . 

(FS pattern^ ... pattern n ) equivalent to F pattern^ followed by F 

pattern 2 ... followed by F pattern n , so that if F 
pattern m fails, edit chain is left at place 
pattern^ < matched. 

(F= expression x) equivalent to (F (as , expression) x), i.e., 

searches for a structure eg to expression, see 
page 9.22. 

(ORF pattern^ ... pattern n ) equivalent to (F (*ANY* pattern^ ... pattern n ) N ) , 

i.e., searches for an expression that is matched 
by either pattern^, patten^. ... or pattern n . 
See page 9.21. 

BF pattern backwards find. Searches in reverse print order, 

beginning with expression immediately before the 
current expression (unless the current expression 
is the top level expression, in which case BF 
searches the entire expression, in reverse order). 
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BP uses the same pattern match routine as F, and 
maxlevel and upf indf lg have the same effect, but 
the searching begins at the end of each list, and 
descends into each element before attempting to 
match that element. If unsuccessful, the search 
continues with the next previous element, etc., 
until the front of the list is reached, at which 
point BF ascends and backs up, etc. 

For example, if the current expression is 

(PROG NIL (SETQ X (SETQ Y (LIST Z))) (COND ( (SETQ W -~) —)) --), F LIST 
followed by BF SETQ will leave the current expression as (SETQ "Y (LIST Z)), as 
will F COND followed by BF SETQ. 

(BF pattern T) search always includes current expression, i.e., 

starts at the end of current expression and works 
backward, then ascends and backs up, etc. 

Thus in the previous example, where F COND followed by BF SETQ found 
(SETQ Y (LIST Z)), F COND followed by (BF SETQ T) would find the (SETQ W --) 
expression . 

(BF pattern) same as BF pattern. 

(BF pattern NIL) 

Location Specification 

Many of the more sophisticated commands described later in this chapter use a 
more general method of specifying position called a location specif icatlon . A 
location specification is a list of edit commands that are executed in the 
normal fashion with two exceptions. First, all commands not recognized by the 
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editor are interpreted as though they had been preceded by F. For example* 
the location specification (COND 2 3) specifies the 3rd element in the first 
clause of the next COND. 26 



Secondly, if an error occurs while evaluating one of the commands in tho 
location specif ication, and the edit chain had been changed, i.e., was not the 
same as it was at the beginning of that execution of the location 
specification, the location operation will continue. In other words, tho 
location operation keeps going unless it reaches a state where it detects that 
it is 'looping', at which point it gives up. Thus, if (COND 2 3) is being 
located, and the first clause of the next COND contained only two elements, tho 
execution of the command 3 would cause an error. The search would then 
continue by looking for the next COND. However, if a point were reached where 
there were no further CONDs, then the first command, COND, would cause the 
error; the edit chain would not have been changed, and so the entire location 
operation would fail, and cause an error. 

The IF command in conjunction with the function provide a way of using 
arbitrary predicates applied to elements in the current expression . IF and 
will be described in detail later in the chapter; along with examples 
illustrating their use in location specifications. 

Throughout this chapter, the meta-symbol @ is used to denote a location 
specification. Thus © is a list of commands interpreted as described above, @ 
can also be atomic, in which case it is interpreted as list[@]. 



25 

Normally such commands would cause errors. 

Note that the user could always write F COND followed by 2 and 3 for 
(COND 2 3) if he were not sure whether or not COND was the name of an 
atomic command. 
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(LC . (?) 



provides a way of explicitly invoking the location 
operation, e.g. (LC COND 2 3) will perform the tho 
search described above. 



(LCL . @) Same as LC except the search is confined to tho 

current expression, i.e., the edit chain is 
rebound during the search so that it looks as 
though the editor were called on just the current 
expression. For example, to find a COND 
containing a RETURN, one might use the location 
specification (COND (LCL RETURN) \) where the \ 
would reverse the effects of the LCL command, and 
make the final current expression be the COND. 

(2ND . @) Same as (LC . 9) followed by another (LC . (?) 

except that if the first succeeds and second 
fails, no change is made to the edit chain. 

(3RD . (?) Similar to 2ND. 

(*• pattern) ascends the edit chain looking for a link which 

matches pattern . In other words, it keeps doing 
O's until it gets to a specified point. If 
pattern is atomic, it is matched with the first 
element of each link, otherwise with the entire 
link. 27 



If pattern is of the form (IF expression), expression is evaluated at each 
link, and if its value is NIL, or the evaluation causes an error, the 
ascent continues. 
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For example: 



app 

[PROG NIL 

(COND 

[ (NULL (SETQ L (CDR L))) 
(COND 

(FLG (RETURN L] 
([NULL (CDR (FMEHB (CAR L) 

(CADR L]] 

*F CADR 
*(*• COND) 

& p 

(COND (& &) (& &)) 



Mote that this command differs from BF in that it does not search inside of 
each link, it simply ascends. Thus in the above example, F CADR followed by 
BF COND would find (COND (FLG (RETURN L))) 9 not the higher COND. 

If no match is found, an error is generated, and 
the edit chain is unchanged. 

(BELOW com x) ascends the edit chain looking for a link 

PR 

specified by com, and stops x ■ links below 
that, 29 i.e. BELOW keeps doing O's until it gets 
to a specified point, and then backs off x O's. 



(BELOW com) same as (BELOW com 1). 

For example, (BELOW COND) will cause the cond clause containing the current 
expression to become the new current expression. Thus if the current 
expression is as shown above, F CADR followed by (BELOW COND) will make the new 



x is evaluated, e.g., (BELOW com (IPLUS X Y) ) . 
Only links that are elements are counted, not tails. 



expression be ([NULL (CDR (FMEMB (CAR L) (CADR L] (GO LP)), and is therefore 
equivalent to 0 0 0 0. 

The BELOW command is useful for locating a substructure by specifying something 
it contains. For example, suppose the user is editing a list of lists, and 
wants to find a sublist that contains a F00 (at any depth). He simply executes 
F FOO (BELOW \). 

(NEX x) same as (BELOW x) followed by NX. 

For example, if the user is deep inside of a SELECTQ clause, he can advance to 
the next clause with (NEX SELECTQ). 

NEX same as (NEX -). 

The atomic form of NEX is useful if the user will be performing repeated 
executions of (NEX x). By simply MARKing (see page 9.34) the chain 
corresponding to x# he can use NEX to step through the sublists. 

(NTH x) generalized NTH command. Effectively performs 

(LCL . x), followed by (BELOW \), followed by UP, 

In other words, NTH locates x, using a search restricted to the current 
expression, and then backs up to the current level, where the new current 
expression is the tail whose first element contains, however deeply, the 
expression that was the terminus of the location operation. For example: 

*p 

(PROG (& &) LP (COND & &) (EDITCOM &) (SETQ UNFIND UF) (RETURN L)) 

* ( NTH UF) 

wp 

... (SETQ UNFIND UF) (RETURN L)) 
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If the search is unsuccessful, NTH generates an 
error and the edit chain is not changed. 

Note that (NTH n) is just a special case of (NTH x), and in fact, no special 
check is made for x a number; both commands are executed identically. 

e.g., (COND . . RETURN). Finds a cond that 
contains a return , at any depth. Equivalent to 
(but more efficient than) (F pattern N), (LCL , (?) 
followed by («- pattern). 

For example, if the current expression is 

(PROG NIL [COND ( (NULL L) (COND (FL6 (RETURN L] --), then (COND RETURN) will 
make (COND (FLG (RETURN L))) be the current expression. Note that it is the 
innermost COND that is found, because this is the first COND encountered when 
ascending from the RETURN. In other words, (pattern ©) is not always 
equivalent to (F pattern N), followed by (LCL . (?) followed by \. 

Mote that 9 is a location specification, not just a pattern. Thus 
(RETURN .. COND 2 3) can be used to find the RETURN which contains a COND 
whose first clause contains (at least) three elements. Note also that since @ 
permits any edit command, the user can write commands of the form 
(COND . . (RETURN COND)), which will locate the first COND that contains a 
RETURN that contains a COND. 



( pattern 



(?) 



30 



An infix command, • . . • is not a meta-symbol, it is the name of the command. 
@ is cddr of the command. 
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9.3.3 Commands That Save and Restore The Edit Chain 



Several facilities are available for saving the current edit chain and later 
retrieving it: MARK, which marks the current chain for future reference, 
which returns to the last mark without destroying it, and which returns to 
the last mark and also erases it. 

HARK adds the current edit chain to the front of the 

list marklst . 

*• makes the new edit chain be (CAR MARKLST). 

Generates an error if marklst is NIL, i.e., no 
MARKs have been performed, or all have beon 
erased. 

similar to *■ but also erases the MARK, i.e., 
performs (SETQ MARKLST (CPR MARKLST) ) . 

Note that if the user has two chains marked, and wishes to return to the first 
chain, he must perform which removes the second mark, and then However, 
the second mark is then no longer accessible. If the user wants to be able to 
return to either of two (or more) chains, he can use the following generalized 
MARK: 

(MARK atom) sets atom to the current edit chain, 

(\ atom) makes the current edit chain become the value of 

atom. 



An atomic command; do not confuse * with the list command (*• pattern). 
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If the user did not prepare in advance for returning to a particular edit 
chain, he may still be able to return to that chain with a single command by 
using \ or \P. 

\ makes the edit chain be the value of unfind . 

Generates an error if unfind=NIL. 



unfind is set to the current edit chain by each command that makes a "big 
jump" , i.e., a command that usually performs more than a single ascent or 
descent, namely t, !NX, all commands that involve a search, e.g., F, LC, 

BELOW, et al and \ and \P themselves. 32 

For example, if the user types F COND, and then F CAR, \ would take him back to 
the COND. Another \ would take him back to the CAR, etc. 

\P restores the edit chain to its state as of the 

last print operation, i.e. P, ?, or PP. If the 
edit chain has not changed since the last 
printing, \P restores it to its state as of the 
printing before that one, i.e., two chains are 
always saved. 

For example, if the user types P followed by 3 2 1 P, \P will return to the 
first P, i.e., would be equivalent to 0 0 Another \P would then take him 

back to the second P, i.e., the user could use \P to flip back and forth 
between the two edit chains. 



op 

Except that unf ind is not reset when the current edit chain is the top 
level expression, since this could always be returned to via the t command. 

Mote that if the user had typed P followed by F COND, he could use either \ 
or \P to return to the P, i.e., the action of \ and \P are independent. 
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(S var . @) 



Sets var (using setq) to the current expression 
after performing (LC . ©). Edit chain is not 
changed. 



Thus (S FOO) will set foo to the current expression, (S FOO - 1 1) will set f oo 
to the first element in the last element of the current expression. 

This ends the section on "Attention Changing Commands. 11 
9.4 Commands That Modify Structure 

The basic structure modification commands in the editor are: 

(n) n > 1 deletes the corresponding element from the 



current expression. 



(n e 




n,m > 1 replaces the nth element in the current 



expression with e 



1 



( -n e 




n,m > 1 inserts e 



e m before the nth element 



in the current expression. 



(N e-, 




m > 1 attaches e 4 ... e m at the end of the current 



expression . 



As mentioned earlier: 



all structure modification done by the editor is destructive . i.e . the editor 
uses rpiaca and rplaed to physically change the structure it was given. 



However, all structure modification is undoable, see UNDO page 9.78. 
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All of the above commands generate errors if the current expression is not a 
list, or in the case of the first three commands, if the list contains fewer 
than n elements. In addition, the command (1), i.e. delete the first element, 
will cause an error if there is only one element, since deleting the first 
element must be done by replacing it with the second element,, and then deleting 
the second element. Or, to look at it another way, deleting the first element 
when there is only one element would require changing a list to an atom (i.e. 
to NIL) which cannot be done. 

9.4.1 Implementation of Structure Modification Commands 

Note: Since all commands that insert, replace, delete or attach structure use 
the same low level editor functions, the remarks made here are valid Jor 
all structure changing commands. 

For all replacement, insertion, and attaching at the end of a list, unless the 

command was typed in directly to the editor, copies of the corresponding 

structure are used, because of the possibility that the exact same command, 

(i.e. same list structure) might be used again. Thus if a program constructs 

the command (1 (A B C)) e.g. via (LIST 1 F00), and gives this command to the 

36 

editor, the (A B C) used for the replacement will not be ecj to f oo . 



However, the command DELETE will work even if there is only one element in 
the current expression, since it will ascend to a point where it can do the 
deletion . 



Some editor commands take as arguments a list of edit commands, e.g. 
(LP F FOO (1 (CAR FOO))). In this case, the command (1 (CAR FOO)) is not 
considered to have been "typed in" even though the LP command itself may 
have been typed in. Similarly, commands originating from macros, or 
commands given to the editor as arguments to editf , editv , et al, e.g. 
E0ITF(FOO F COND (N --)) are not considered typed in. 



The user can circumvent this by using the I command, which computes the 
structure to be used. In the above example, the form of the command would 
be (I 1 FOO), which would replace the first element with the value of foo 
itself. See page 9.62. 



9.37 



The rest of this section is included for applications wherein the editor is 
used to modify a data structure,, and pointers into that data structure are 
stored elsewhere. In these cases, the actual mechanics of structure 
modification must be known in order to predict the effect that various commands 
may have on these outside pointers. For example, if the value of foo is cdr of 
the current expression, what will the commands (2), (3), (2 X Y Z), (-2 X Y Z), 
etc . do to foo ? 

Deletion of the first element in the current expression is performed by 
replacing it with the second element and deleting the second element by 
patching around it. Deletion of any other element is done by patching around 
it, i.e., the previous tail is altered. Thus if foo is eg to the current 
expression which is (A BCD), and fie is cdr of foo , after executing the 
command (1), foo will be (B C D) (which is equal but not eg to fie) . However, 
under the same initial conditions, after executing (2) f ie will be unchanged, 
i.e., fie will still be (B C D) even though the current expression and foo are 
now (A CD). 37 

Both replacement and insertion are accomplished by smashing both car and cdr of 
the corresponding tail. Thus, if foo were eg to the current expression, 
(A B C D), after (I X.' Y Z), foo would be (X Y Z B C D). Similarly, if foo were 
eg to the current expression, (A B C D), then after (-1 X Y Z) , foo would be 
(XYZABCD). 

The N command is accomplished by smashing the last cdr of the current 



A general solution of the problem just isn't possible, as it would require 
being able to make two lists ecj to each other that were originally 
different. Thus if fie is cdr of the current expression, and f urn is ccldr 
of the current expression, performing (2) would have to make f ie be ejj to 
fun if all subsequent operations were to update both fie and fum correctly. 
Think about it. 
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expression a la nconc * Thus if foo were eg to any tail of the current 
expression, after executing an M command, the corresponding expressions would 
also appear at the end of foo . 

In summary, the only situation in which an edit operation will not change an 
external pointer occurs when the external pointer is to a proper tail of the 
data structure, i.e., to cdr of some node in the structure, and the operation 
is deletion. If all external pointers are to elements of the structure, i.e., 
to car of some node, or if only insertions, replacements, or attachments are 
performed, the edit operation will always have the same effect on an external 
pointer as it does on the current expression. 

9.4.2 The A, B, and : Commands 

In the (n), (n e^ ... e m ), and (-n 6j ... ® m ) commands, the sign of the 
integer is used to indicate the operation. As a result, there is no direct way 
to express insertion after a particular element, (hence the necessity for a 
separate H command). Similarly, the user cannot specify deletion or 
replacement of the nth element from the end of a list without first converting 
n to the corresponding positive integer. Accordingly, we have: 

(Be. ... e ) inserts e^ ... e before the current expression. 



For example, to insert FOO before the last element in the current expression, 
perform -1 and then (B FOO). 



Equivalent to UP followed by (-1 e 



1 




(A e 



1 




inserts e^ ... e m after the current expression. 
Equivalent to UP followed by (-2 e^ ... e m ) or 
(N e. ... e ) whichever is appropriate. 
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( : . .. e m ) replaces the current expression by e j , ., e m « 

Equivalent to UP followed by (I e ( e m ) . 

DELETE or (:) deletes the current expression. 

DELETE first tries to delete the current expression by performing an UP and 
then a (1). This works in most cases. However, if after performing UP, the 
new current expression contains only one element, the command ( 1 ) will not 
work. Therefore, DELETE starts over and performs a BK, followed by UP, 
followed by (2). For example, if the current expression is 
(COND ( (MEMB X Y)) (T Y)), and the user performs -i, and then DELETE, the 
BK-UP-(2) method is used, and the new current expression will be ... 
( (MEMB X Y) ) ) 

However, if the next higher expression contains only one element, BK will not 
work. So in this case, DELETE performs UP, followed by ( : NIL), i.e., it 
replaces the higher expression by NIL. For example, if the current expression 
is (COND ((MEMB X Y)) (T Y)) and the user performs F MEMB and then DELETE, the 
new current expression will be . . , NIL (T Y)) and the original expression would 
now be (COND NIL (T Y)). The rationale behind this is that deleting (MEMB X Y) 
from ((MEMB X Y)) changes a list of one element to a list of no elements, i.e., 
( ) or NIL. 

If the current expression is a tail, then B, A, :, and DELETE all work exactly 
the same as though the current expression were the first element in that tail. 
Thus if the current expression were ... (PRINT Y) (PRINT 2)), (B (PRINT X)) 
would insert (PRINT X) before (PRINT Y), leaving the current expression 
... (PRINT X) (PRINT Y) (PRINT Z)). 
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The following forms of the A, B, and : commands incorporate a location 
specification : 



(INSERT e 1 ... e m BEFORE . @) 3S Similar to (LC .0) 39 followed by (B 



l m 



up 

(PROG (& & X) "COMMENT** (SELECTQ ATM & NIL) (OR & &) (PRIN1 & T) 

(PRIN1 & T) (SETO X & 

*( INSERT LABEL BEFORE PRIN1) 

a p 

(PROG (& &' X) "COMMENT** (SELECTQ ATM & NIL) (OR & &) LABEL 

(PRIN1 & T) ( 4(? 



Current edit chain is not changed, but unf ind is 
set to the edit chain aft&r the B was performed, 
i.e. \ will make the edit chain be that chain 
where the insertion was performed. 



(INSERT e 



1 



e m AFTER . 9) Similar to INSERT BEFORE except uses A instead of 
m 

B. 



(INSERT e 1 ... e m FOR . (?) similar to INSERT BEFORE except uses : for B, 



35 



i.e. @ is cdr[member[ BEFORE ; command]] 



39 



except that if @ causes an error, the location process does not continue as 
described on page 9.29. For example if @=( COND 3) and the next COND does 
not have a 3rd element, the search stops and the INSERT fails. Note that 
the user can always write (LC COND 3) if he intends the search to continue. 



40 



Sudden termination of output followed by a blank line return indicates 
printing was aborted by control-E. 
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(REPLACE 9 WITH e, ....... e m )^ Here ® 42 is the segment of the command between 

REPLACE and WITH. Same as 

(INSERT e 1 ... e m FOR . 9). 

Example: (REPLACE COND -1 WITH (T (RETURN L))) 

( CHANGE @ TO e % ... © m ) Same as REPLACE WITH. 

(DELETE . @) does a (LC . Q) 43 followed by DELETE. Current 

edit chain is not changed, ^ but unf ind is set to 
the edit chain after the DELETE was performed. 

Example: (DELETE -1), (DELETE COND 3) 



{Vote: if (V is MIL (i.e. empty), the corresponding operation is performed here 
(on the current edit chain) . 



For example, (REPLACE WITH (CAR X)) is equivalent to (: (CAR X)). For added 
readability, HERE is also permitted, e.g. (INSERT (PRINT X) BEFORE HERE) will 
insert (PRINT X). before the current expression (but not change the edit 
chain) . 



Note*. @ does not have to specify a location within the current expression . i.e. 
it is perfectly legal to ascend to INSERT, REPLACE, or DELETE 



41 
42 
43 
44 



BY can be used for WITH. 
See footnote on page 9.41. 
See footnote on page 9.41. 

Unless the current expression is no longer a part of the expression being 
edited, e.g. if the current expression is ... C) and the user performs 
(DELETE 1), the tail, (C), will have been cut off. Similarly, if the 
current expression is (CDR Y) and the user performs (REPLACE WITH (CAR X)). 
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For example, (INSERT (RETURN) AFTER ? PROG -1) will go to the top p find tho 
first PROG, and insert a (RETURN) at its end, and not change the current edit 
chain. 

The A, B, and : commands, commands, (and consequently INSERT, REPLACE, and 
CHANGE), all make special checks in ej thru e m for expressions of the form 
. corns). In this case, the expression used for inserting or replacing is a 
copy of the current expression after executing corns , a list of edit commands. 
For example, (INSERT (« F COND -1 -1) AFTER 3) 46 will make a copy of the last 
form in the last clause of the next cond , and insert it after the third element 
of the current expression. 



9.4.3 Form Oriented Editing and the Role of UP 

The UP that is performed before A, B, and : commands^ makes these operations 
form-oriented. For example, if the user types F SETQ, and then DELETE, or 
simply (DELETE SETQ), he will delete the entire SETQ expression* whereas 
(DELETE X) if X is a variable, deletes just the variable X, In both cases, the 
operation is performed on the corresponding form, and in both cases is probably 
what the user intended. Similarly, if the user types 

(INSERT (RETURN Y) BEFORE SETQ) , he means before the SETQ expression, not 



45 

The execution of corns does not change the current edit chain. 

46 A r ot (INSERT F COND -1 (## -1) AFTER 3), which inserts four elements after 
the third element, namely F, COND, -1, and a copy of the last element in 
the current expression. 

47 

and therefore in INSERT, CHANGE, REPLACE, and DELETE commands after the 
location portion of the operation has been performed. 
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before the atom SETQ. A consequent of this procedure is that a pattern of the 
form (SETQ Y --) can be viewed as simply an elaboration and further refinement 
of the pattern SETQ. Thus (INSERT (RETURN Y) BEFORE SETQ) and 
(INSERT (RETURN Y) BEFORE (SETQ Y --)) perform the same operation 49 and, in 
fact, this is one of the motivations behind making the current expression after 
F SETQ, and F (SETQ Y be the same. 

Occasionally, however, a user may have a data structure in which no special 
significance or meaning is attached to the position of an atom in a list, as 
INTERLISP attaches to atoms that appear as car of a list, versus those 
appearing elsewhere in a list. In general, the user may not even know whether 
a particular atom is at the head of a list or not. Thus, when he writes 
(INSERT expression BEFORE FOO), he means before the atom F00, whether or not it 
is car of a list. By setting the variable upf indf Ig to Nil, 5 ** the user can 
suppress the implicit UP that follows searches for atoms, and thus achieve the 
desired effect. With upf indf Ig sNIL, following F FOO, for example, the current 
expression will be the atom FOO. In this case, the A, B, and : operations will 
operate with respect to the atom FOO. If the user intends the operation to 
refer to the list which FOO heads, he simply uses instead the pattern (FOO . 



48 



49 



There is some ambiguity in (INSERT expr AFTER functionname ) , as the user 
might mean make expr be the function's first argument. Similarly, the user 
cannot write (REPLACE SETQ WITH SETQQ) meaning change the name of the 
function. The user must in these cases write (INSERT expr AFTER 
functionary 1), and (REPLACE SETQ 1 WITH SETQQ). 

assuming the next SETQ is of the form (SETQ Y --). 



60 Initially, and usually, set to T. 
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9.4.4 Extract and Embed 



Extraction involves replacing the current expression with one of its 
subexpressions (from any depth). 

(XTR . (?) replaces the original current expression with tho 

expression that is current after performing 
(LCL . @). 51 

For example, if the current expression is (COND ( (NULL X) (PRINT Y) ) ) , 
(XTR PRINT), or (XTR 2 2) will replace the cond by the print . 

If the current expression after (LCL . (?) is a 
tail of a higher expression, its first element is 
used. 

For example, if the current expression is (COND ((NULL X) Y) (T Z)), then 
(XTR Y) will replace the cond with Y; even though the current expression after 
performing (LCL Y) is ... Y). 

If the extracted expression is a list, then after 
XTR has finished, the current expression will be 
that list. 

Thus, in the first example, the current expression after the XTR would be 
(PRINT Y). 



SI 

See footnote on page 9.41. 



9.45 



If the extracted expression is not a list, the now 
current expression will be a tail whose first 
element is that non-list. 

Thus, in the second example, the current expression after the XTR would bo 
. . . Y followed by whatever followed the COND. 

If the current expression initially is a tail, extraction works exactly the 
same as though the current expression were the first element in that tail. 
Thus if the current expression is ... (COND ( (NULL X) (PRINT Y) ) ) (RETURN Z)), 
then ( XTR PRINT) will replace the cond by the print , leaving (PRINT Y) as the 
current expression. 

The extract command can also incorporate a location specification: 

(EXTRACT @ j FROM . @ 2 ) 62 Performs (LC . @ 2 ) 63 and then (XTR . Current 

edit chain is not changed, but unf ind is set to 
the edit chain after the XTR was performed. 

Example: If the current expression is (PRINT (COND ((NULL X) Y) (T Z))) then 
following (EXTRACT Y FROM COND), the current expression will be (PRINT Y). 
(EXTRACT 2 -1 FROM COND), (EXTRACT Y FROM 2), (EXTRACT 2 -1 FROM 2) will all 
produce the same result. 



@j is the segment between EXTRACT and FROM. 

S3 

See footnote on page 9.41. 
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While extracting replaces the current expression by a subexpression , embedding 
replaces the current expression with one containing it as a subexpression. 

(MBD e 1 ... e m ) MBD substitutes^ the current expression for all 

instances of the atom a in 8j ... e m , and replaces 
the current expression with the result of that 
substitution. 

Examples: If the current expression is (PRINT Y), 

(MBD (COND ((NULL X) *) ((NULL (CAR Y) ) « (GO LP)))) would replace ( PRINT Y) 
with (COND ((NULL X) (PRINT Y) ) ( (NULL (CAR Y)) (PRINT Y) (GO LP))). 

If the current expression is (RETURN X), (MBD (PRINT Y) (AND FLG «) ) would 
replace it with the two expressions (PRINT Y) and (AND FLG (RETURN X) ) i.e., if 
the (RETURN X) appeared in the cond clause (T (RETURN X)), after the MBD, the 
clause would be (T (PRINT Y) (AND FLG (RETURN X))). 

If * does not appear in e^ ... e m , the MBD is 
interpreted as (MBD (ej ... e m *))..,' 

Examples: If the current expression is (PRINT Y), then (MBD SETQ X) will 
replace it with (SETQ X (PRINT Y)). If the current expression is (PRINT Y), 
(MBD RETURN) will replace it with (RETURN (PRINT Y)). 

MBD leaves the edit chain so that the larger expression is the new current 
expression. 



as with subst , a fresh copy is used for each substitution. 
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If the current expression initially is a tail, embedding works exactly the same 
as though the current expression were the first element in that tail. Thus if 
the current expression were ... (PRINT Y) (PRINT Z)), (MBD SETQ X) would 
replace (PRINT Y) with (SETQ X ( PRINT Y)). 

The embed command can also incorporate a location specification: 

( EMBED & IN . x) 65 does (LC . Q) 66 and then (MBD . x). Edit chain is 

not changed, but unf ind is set to the edit chain 
after the MBD was performed. 

Example: ( EMBED PRINT IN SETQ X), (EMBED 3 2 IN RETURN) , 
( EMBED COND 3 1 IN (OR * (NULL X)).). 

WITH can be used for IN, and SURROUND can be used for EMBED, e.g., (SURROUND 
NUMBERP WITH (AND * (MINU5P X))). 

9.4.5 The MOVE Command 

The MOVE command allows the user to specify (1) the expression to be moved, (2) 
the place it is to be moved to, and (3) the operation to be performed there, 
e.g., insert it before, insert it after, replace, etc. 

(MOVE TO com . § z ) 67 where com is BEFORE, AFTER, or the name of a list 



@ Is the segment between EMBED and IN. 

See footnote on page 9.41. 

@* is the segment between MOVE and TO. 
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command, e.g., N, etc. performs (LC . Gj), 
and obtains the current expression there (or its 
first element, if it is a tail), which we will 
call expr ; MOVE then goes back to the original 
edit chain, performs (LC . @ 2 ) followed by 
(com expr), 5 ^ then goes back to and deletes 
expr . Edit chain is not changed. Unf ind is set 
to edit chain after (com expr) was performed. 

For example, if the current expression is (ABC D), (MOVE 2 TO AFTER 4) will 
make the new current expression be (A C D B). Note that 4 was executed as of 
the original edit chain, and that the second element had not yet boon 
removed. 

As the following examples taken from actual editing will show, the MOVE command 
is an extremely versatile and powerful feature of the editor. 



a? 

(PROG ((L L) ) (EDLOC (CDDR C)) (RETURN (CAR L) ) ) 
*(MOVE 3 TO : CAR) 

JSC ? 

(PROG ((L L)) (RETURN (EDLOC (CODRC)))) 

... (SELECTQ OBJPR & &) (RETURN &) LP2 (COND & &)) 

*(MOVE 2 TO N 1) 
«P 

... (SELECTQ OBJPR & & &) LP2 (COND & &)) 



58 
59 
60 



see footnote on page 9.41, 

Setting an internal flag so expr is not copied. 

If @£ specifies a location inside oj the expression to be moved, a message 
is printed and an error is generated, e.g. (MOVE 2 TO AFTER X), where X is 
contained inside of the second element. 
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»p 

(OR (EQ X LASTAIL ) (NOT &) (AND & & &)) 

"(MOVE 4 TO AFTER (BELOW CONO)) 

*P 

(OR (EQ X LASTAIL) (NOT &)) 
*\ P 

,..(&&) (AND & & &) (T & &)) 



*P 

((NULL X) ""COMMENT** (COND & &)) 

*(-3 (GO NXT] 

* (MOVE 4 TO N (- PROG) ) 
*p 

((NULL X) * "COMMENT"" (GO NXT) ) 
*\ P 

(PROG (&) «*COMMENT«" (COND & & &) (COND & & 8.) (COND 8. &)) 

" ( INSERT NXT BEFORE -1) 

*P 

(PROG (&) ""COMMENT"* (COND & & &) (COND & & &) NXT (COND & &)) 



Note that in the last example, the user could have added the prog label NXT and 
moved the cond in one operation by performing (MOVE 4 TO N (*■ PROG) (N NXT)). 
Similarly, in the next example, in the course of specifying @ 2 » the location 
where the expression was to be moved to, the user also performs a structure 
modification, via ( N ( T ) ) , thus creating the structure that will receive the 
expression being moved. 



* p 

( ( CDR &) ""COMMENT** (SETQ CL &) (EDITSMASH CL &.<&')) 
"MOVE 4 TO N 0 (N (T)) -1] 

"P 

((CDR &) ""COMMENT** (SETQ CL &)) 
*\ p 

»(T (EDITSMASH CL & &)) 



If (? 2 is NIL, or (HERE), the current position specifies where the operation is 
to take place. In this case, unf ind is set to where the expression that was 
moved was originally located, i.e. 0j. For example: 



«P 

(TENEX) 

"(MOVE f F APPLY TO N HERE) 

*P 

(TENEX (APPLY & &)) 
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* p 

(PROG (& & & ATM IND VAL) (OR & &) ^COMMENT*® (OR & &) (PRINi & T) ( 
PRIN1 & T) (SETQ IND 

*(MOVE * TO BEFORE HERE) 
» p 

(PROG (& & & ATM IND VAL) (OR & &) (OR & &) (PRINI & 

ftp 

(T (PRINI C-EXP T)) 

*(MOVE f BF PRINI TO N HERE) 
ft p 

(T (PRINI C-EXP T) (PRINI & T)) 



Finally, if @j is NIL, the HOVE command allows the user to specify where the 
current expression is to be moved to. In this case, the edit chain is changed, 
and is the chain where the current expression was moved to; unf ind is set to 
v/here it v/as. 



ft p 

(SELECTQ OBJPR (&) (PROGN & &)) 

*(MOVE TO BEFORE LOOP) 

ftp 

... (SELECTQ OBJPR & &) LOOP (FRPLACA DFPRP &) (FRPLACD DFPRP 
&) (SELECTQ 



9.4.6 Commands That "Hove Parentheses" 

The commands presented in this section permit modification of the list 
structure itself, as opposed to modifying components thereof. Their effect can 
be described as inserting or removing a single left or right parenthesis, or 
pair of left and right parentheses. Of course, there will always be the same 
number of left parentheses as right parentheses in any list structure, since 
the parentheses are just a notational guide to the structure provided by print . 
Thus, no command can insert or remove just one parenthesis, but this is 
suggestive of what actually happens. 



G1 Sudden termination of output followed by a blank line indicates printing 
was aborted by control-E. 



9.51 



In all six commands* n and m are used to specify an element of a list, usually 
of the current expression. In practice, n and m are usually positive or 
negative integers with the obvious interpretation . However, all six commands 
use the generalized NTH command, page 9,32, to find their element(s), so that 
nth element means the first element of the tail found by performing (MTH n). 
In other words, if the current expression is 

(LIST (CAR X) (SETQ Y (CONS W Z))), then (BI 2 CONS), (BI X -1), and (BI X 2) 

all specify the exact same operation. 

All six commands generate an error if the element is not found, i.e. the NTH 
fails. All are undoable. 

(BI n m) both in, inserts a left parentheses before the nth 

element and after the mth element in the current 
expression. Generates an error if the mth element 
is not contained in the nth tail, i.e., the mth 
element must be "to the right" of the nth element. 

Example: If the current expression is (A B (C D E) F G), then (BI 2 4) will 
modify it to be (A (B (C D E) F) 6). 

(BI n) same as (BI n n). 

Example: If the current expression is (A B (C 0 E) F G), then (BI -2) will 
modify it to be (A B (C D E) (F) G) . 

(BO n) both out. Removes both parentheses from the nth 

element;. Generates an error if nth element is not 
a list. 

Example: If the current expression is (A B (C D E ) F G), then (BO 0) will 
modify it to be (A B C 0 E F 6). 
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(LI n) left in, inserts a left parenthesis before the nth 

element (and a matching right parenthesis at the 
end of the current expression), i.e. equivalent 
to (BI n -1). 

Example: if the current expression is (A B (C 0 E) F G) P then (LI 2) will 
modify it to be (A (B (C 0 E) F G ) ) . 

(LO n) left out, removes a left parenthesis from the nth 

element. All elements following the nth element 
are deleted. Generates an error if nth element is 
not a list. 

Example: If the current expression is (A B (C D E) F 6) , then (LO 3) will 
modify it to be (A B C 0 E ) . 

(RI n m) right in, inserts a right parenthesis after the 

mth element of the nth element. The rest of the 
nth element is brought up to the level of the 
current expression. 

Example: If the current expression is (A (B C D E) F G) , (RI 2 2) will modify 
it to be (A (B C) D E F G). Another way of thinking about RI is to read it as 
"move the right parenthesis at the end of the nth element in to after its mth 
element." 

(RO n) right out, removes the right parenthesis from the 

nth element, moving it to the end of the current 
expression. All elements following the nth 
element are moved inside of the nth element . 
Generates an error if nth element is not a list. 
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Example:: if the current expression is (A B (C 0 E) F G), (RO 3) will modify it 

to be (A B (C D E F 6)). Another way of thinking about RO is to read it as 

"move the right parenthesis at the end of the nth element out to the end of 
the current expression." 

9.4.7 TO and THRU 

EXTRACT, EMBED, DELETE, REPLACE, and MOVE can be made to operate on several 
contiguous elements, i.e., a segment of a list, by using in their respective 
location specifications the TO or THRU command. 

does a (LC . followed by an UP, and then a 

(BI i @ 2 )» thereb y grouping the segment into a 
single element, and finally does a 1, making the 
final current expression be that element. 

For example, if the current expression is (A (B (C D) (E) (F 6 H) I) J K) p 
following (C THRU G) , the current expression will be ((C D) (E) (F G H) ) . 

TO 5 2 ) Same as THRU except last element not included, 

i.e., after the BI, an (RI 1 ~2) is performed. 

If both @£ and $ 2 are numbers, and @ 2 is greater than @j, then @ 2 co ^nts from 
the beginning of the current expression, the same as @j. In other words, if 
the current expression is (A B C D E F 6), (.3 THRU 5) means (C THRU E) not 
(C THRU G). In this case, the corresponding BI command is (Bi t (^-©j+l). 

THRU and TO are not very useful commands by themselves; they are intended to be 
used in conjunction with EXTRACT, EMBED, DELETE, REPLACE, and MOVE . After THRU 
and TO have operated, they set an internal editor flag informing the above 



THRU @ 2 ) 
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commands that the element they are operating on is actually a segment, and that 
the extra pair of parentheses should be removed when the operation is complete. 
Thus : 



*P 

(PROG (& & ATM IND VAL WORD) (PRIN1 & T) (PRIM1 & T) (SETQ IND &) (SETQ VAL &) 
**COMMENT*« (SETQQ 

*(MOVE (3 THRU 4) TO BEFORE 7) 

« p 

(PROG (& & ATM IND VAL WORD) (SETQ IND &) (SETQ VAL &) (PRIN1 & T) (PRIN1 & T) 
**COMMENT«* 



ftp 

(* FAIL RETURN FROM EDITOR, USER SHOULD NOTE THE VALUES OF SOURCEXPR AND 

CURRENTFORM. CURRENTFORM IS THE LAST FORM IN SOURCEXPR WHICH WILL HAVE BEEN 

TRANSLATED, AND IT CAUSED THE ERROR.) 

* ( DELETE (USER THRU CURRS)) 

=CURRENTFORM . 

ftp 

(" FAIL RETURN FROM EDITOR. CURRENTFORM IS 



ap 

...LP (SELECTO & & & & NIL) (SETQ Y &) OUT (SETQ FLG &) (RETURN Y) ) 
"(MOVE (1 TO OUT) TO N HERE] 

»p 

... OUT (SETQ FLG &) (RETURN Y) LP (SELECTQ & & & 6 NIL) (SETQ Y &)) 



"PP 

[ PROG (RF TEMPI TEMP2) 
(COND 

((NOT (MEMB REMARG LISTING)) 

(SETQ TEMPI (ASSOC REMARG NAMEDREMARKS ) ) ""COMMENT"" 
(SETQ TEMP2 (CADR TEMPI)) 
(GO SKIP)) 
(T ""COMMENT** 
(SETQ TEMPI REMARG))) 
(NCONC1 LISTING REMARG) 
( COND 

((NOT (SETQ TEMP2 (SASSOC 

"(EXTRACT (SETQ THRU CADR) FROM COND) 

« p 

(PROG (RF TEMPI TEMP2 ) (SETQ TEMPI &) ""COMMENT** (SETQ TEMP2 &) 

( NCONC1 LISTING REMARG) (COND & & 

ft 
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TO and THRU can also be used directly with XTR. Thus in the previous example, 
if the current expression had been the COND, e.g. the user had first performed 
F COND, he could have used (XTR (SETQ THRU CADR) ) to perform the extraction. 



(@ 1 TO) , ( © j THRU) both same as (@| THRU -1 ) , i.e. . from @j through 

the end of the list. 



Examples: 

sat p 

(VALUE (RPLACA DEPRP &) (RPLACD &) (RPLACA VARSWORO &) (RETURN) ) 
* ( MOVE (2 TO) TO N (- PROG) ) 
*(N (GO VAR ) ) 
*p 

(VALUE (GO VAR)) 



*P 

(T ""COMMENT**. (COND &) **COMMENT*« (EDITSMASH CL & &) (COND &)) 
*(-3 (GO REPLACE) ) 

* ( MOVE (COND TO) TO N t PROG (N REPLACE)) 

«p 

(T --COMMENT** (GO REPLACE ) ) 

*\ P 

( PROG (&) ""COMMENT** ( COND & & &) (COND & & &) DELETE (COND & &) 
REPLACE (COND &) ** COMMENT** (EDITSMASH CL & &) (COND &)) 



Because XTR involves a location specification while A, B, :, and MBD do 
not . 
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«pp 

[LAMBDA (CLAUSALA X) 
(PROG (AD) 

(SETQ A CLAUSALA) 
LP (COND 

((NULL A) 
(RETURN))) 
(SERCH X A) 
( RUMARK (CDR A)) 
(NOTICECL (CAR A)) 
(SETQ A (CDR A)) 
(GO LP] 

a ( EXTRACT (SERCH THRU NOTS) FROM PROG) 
=NOTICECL 

(LAMBDA (CLAUSALA X) (SERCH X A) (RUMARK &) (NOTICECL &)) 
* ( EMBED (SERCH TO) IN (MAP CLAUSALA (FUNCTION (LAMBDA (A) "] 
*PP 

[LAMBDA (CLAUSALA X) 

(MAP CLAUSALA (FUNCTION (LAMBDA (A) 
(SERCH X A) 
(RUMARK (CDR A)) 
(NOTICECL (CAR A] 



9.4.8 The R Command 

(R x y) replaces all instances of x by £ in the current 

expression, e.g., (R CAADR CADAR). Generates an 
error if there is not at least one instance. 

The R command operates in conjunction with the search mechanism of the editor. 
The search proceeds as described on page 9.23-25, and x can employ any of the 
patterns on page 9.21-23. Each time x matches an element of the structure, the 
element is replaced by (a copy of) j;; each time x matches a tail of the 
structure, the tail is replaced by (a copy of) 

For example, if the current expression is (A (B C) (B . C)), 

(R C D) will change it to ( A (B D) (B . D) ) , 

(R ( . . . . C) D) to (A (B C) (B . D)), 

(R C (D E)) to (A (B (D £)) (B D E))y and 

(R (... . NIL) D) to (A (B C . 0) (B . C) . 0). 
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If x is an atom or string containing alt-modes, alt«mod©s appearing in y stand 
for the characters matched by the corresponding alt-mode in x. For example, 
(R FOOS FIES) means for all atoms or strings that begin with FOO, replace the 
characters 'POO 1 by 'FIE*. 63 Applied to the list 

(FOO F002 XFOOl ) f (R FOOS FIES) would produce (FIE FIE2 XFOOl), and 
(R SFOOS SFIES) would produce (FIE FIE2 XFIE1). Similarly, (R SDS SAS) will 
change (LIST (CADR X) (CADDR Y) ) to (LIST (CAAR X) (CAADR)). 64 

The user will be informed of all such alt-mode replacements by a message of the 
form x->y, e.g. CADR->CAAR« 

Note that the S feature can be used to delete or add characters, as well as 
replace them. For example, (R $1 S) will delete the terminating I's from all 
literal atoms and strings. Similarly, if an alt-mode in x does not have a mate 
in x< the characters matched by the $ are effectively deleted. For example, 
(R S/S S) will change AND /OR to AND. 65 % can also be a list containing 
alt-modes, e.g. (R SI (CAR $)) will change F001 to (CAR FOO), FIE1 to 
(CAR FIE). 

If x does not contain alt-modes, $ appearing in £ refers to the entire 



If x matches a string, it will be replaced by a string. Note that it doos 

not~ matter whether x or £ themselves are strings, i.e. 

(R SDS SAS), (R "SDS" SAS) , (R SDS "SAS"), and (R "SDS" "SAS") are 

equivalent. Note also that x will never match with a number, i.e. 
(R SI $2) -.will not change 11 to ""l 2. 



Note that CADDR was wot changed to CAAAR, i.e. (R SDS SAS) does not moan 

replace every D with A, but replace the first D in every atom or string by 

A. If the user wanted to replace every D by A, he could perform 
(LP (R SDS SAS)). 



However, there is no similar operation for changing AND/OR to OR, since the 
first $ in £ always corresponds to the first S in x, the second $ in y to 
the second in Xp etc. 
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expression matched by x, e.g. (R LONGATOM f S) changes LONGATOM to * LONGATOM, 
(R (SETO X &) (PRINT S)) changes every (SETQ X &) to (PRINT (SETQ X &)). 66 



Since (R SxS SyS) is a frequently used operation for replacing characters , tho 
following command is provided: 

(RC x y) equivalent to (R SxS SyS) 

R and RC change all instances of x to The commands Rl and RC1 are available 
for changing just one, (i.e. the first) instance of x to 

(Rl x y) find the first instance of x and replace it by 

(RC1 x y) (R! SxS SyS). 

In addition, while R and RC only operate within the current expression, Rl and 
RC1 will continue searching,, a la the F command, until they find an instance of 
x, even if the search carries them beyond the current expression. 

( SW n m) switches the nth and mth elements of the current 

expression. 

For example, if the current expression is 

(LIST (CONS (CAR X) (CAR Y) ) (CONS (COR X) (CDR Y) ) ) , 

(SW 2 3) will modify it to be 

(LIST (CONS (CDR X) (CDR Y)) (CONS (CAR X) (CAR Y))). The relative order of n 
and m is not important, i.e., (SW 3 2) and (SW 2 3) are equivalent. 



If x is a pattern containing an alt-mode pattern somewhere within it, tho 
characters matched by the alt-modes are not available, and for the purposes 
of replacement, the effect is the same as though x did not contain any alt- 
modes. For example, if the user types (R (CAR FS) (PRINT $)), the second $ 
will refer to the entire expression matched by (CAR F$). 
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SW uses the generalized NTH command to find the 
nth and mth elements, a la the BI-BO commands. 

Thus in the previous example, (SW CAR CDR) would produce the same result. 



9.5 '. Commands' That Print 

PP prettyprints the current expression. 

P prints the current expression as though printlevel 

were set to 2. 

(P m) prints mth element of current expression as though 

printlevel were set to 2. 

(P 0) same as P 

(P m n) prints mth element of current expression as though 

printlevel were set to n . 

( P 0 n ) prints current expression as though printlevel 

were set to n. 

? same as (P 0 iOO) 

Both (P m) and (P m n) use the generalized NTH command to obtain tho 
corresponding element, so that m does not have to be a number, e.g. (P COND 3) 
will work. PP causes all comments to be printed as »*C0MMENT«« (see Section 
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14). P and ? print as fttt COMMENT ftft only those comments that are (top level) 
elements of the current expression. 

PP 5 * prettyprints current expression, including 

comments. 

PP* is equivalent to PP except that it first resets / **dommen-t*»f'lg to NIL (see 
Section 14). In fact, it is defined as (RESETVAR «*COMMENT«»FLG NIL PP), see 
page 9.77. 

PPV prettyprints current expression as a variable, 

i.e. no< special treatment for LAMBDA, COND, SETQ, 
etc. , or for CLISP. 

PPT prettyprints current expression, printing CLISP 

translations, if any. 

All printing functions print to the terminal , regardless of the primary output 
file. All use the readtafole T. Wo printing function ever changes the edit 
chain. All record the current edit chain for use by \P, page 9.35. All can bo 
aborted with control-E. 



Lower expressions are not really seen by the editor; the printing command 
simply sets printlevel and calls print . 
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9.6 Commands That Evaluate 



Example : *E ■■ BREAK (FIE'- FUN) 
(FIE FUM) 
*E (FOO) 

(FIE BROKEN) 



only when typed in, 6 ** causes the editor to call 

fiQ 

lispx giving it the next input as argument. 



(Ex) 



evaluates x* ** G » performs eval[x], and prints 
the result on the terminal. 



(E xT) 



same as (E x) but does not print, 



the (E x) and (E x T) commands are mainly intended for use by macros and 
subroutine calls to the editor; the user would probably type in a form for 
evaluation using the more convenient format of the (atomic) E command. 



(I c Xj . x n ) 



same as (C y^ ... y n ) where y J seval[x i ] < 



Example: (I 3 (GETD ( QUOTE FOO))) will replace the 3rd element of the current 
expression with the definition of foo/° (I N FOO (CAR FIE)) will attach the 
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e .g, ( INSERT D BEFORE E) will treat E as a pattern, and search for E . 

lispx is used by evalqt and break for processing terminal inputs. If 
nothing else is typed on the same line, lispx evaluates its argument . 
Otherwise, lispx applies it to the next input. In both cases, lispx prints 
the result. See above example, and Sections 2 and 22. 

The I command sets an internal flag to indicate to the structure 
modification commands not to copy expression( s ) when inserting, replacing, 
or attaching. 
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value of f oo and car of the value of. fie. to the end of the current., expression . 
(I F= FOO T) will search for an expression eg to the value of foo. 

If c is not an atom, c is evaluated also. 

Example: (I (COND ((NULL FLG) (QUOTE -1)) (T 1 ) ) POO) , if fig is NIL, inserts 
the value of foo before the first element of the current expression, otherwise 
replaces the first element by the value of foo . 

##[com 1 ;com 2 ; ... ;com n ] is an NLAMBDA, NOSPREAD function (not a command) , 

Its value is what the current expression would bo 
after executing the edit commands com^ ... com n 
starting from t)ie present edit chain. Generates 
an error if any of com^ thru com n cause errors. 
The current edit chain is never changed. 71 

Example: (I R (QUOTE X) (« (CONS ... I))) replaces all X's in the current 
expression by the first cons containing a Z. 

The I command is not very convenient for computing an entire edit command for 
execution, since it computes the command name and its arguments separately. 
Also, the I command cannot be used to compute an atomic command. The following 
two commands provide more general ways of computing commands. 

( COMS x 1 ... x n ) Each x i is evaluated and its value is executed as 

:. „a command. ..- 



Recall that A, B, :, INSERT, REPLACE, and CHANGE make special checks for 
forms in the expressions used for inserting or replacing, and use a copy of 
form instead (see page 9.43). Thus, (INSERT (#13 2) AFTER 1) is 
equivalent to (I INSERT (COPY (##3 2)) (QUOTE AFTER) 1). 
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For example, (COMS (COND (X (LIST IX)))) will replace the first element of the 
current expression with the value of x if non-NIL, otherwise do nothing, 72 

(COMSQ corrij ... com n ) executes com^ ... com n . 

COMSQ is mainly useful in conjunction with the COMS command. For example, 
suppose the user wishes to compute an entire list of commands for evaluation, 
as opposed %o computing each command one at a time as does the COMS command. 
He would then write (COMS (CONS (QUOTE COMSQ) x)) where x computed the list of 
commands, e.g. , (COMS (CONS (QUOTE COMSQ) (GETP F00 (QUOTE COMMANDS)))). 



9.7 Commands That Test 

< ' " "" 1 ■' ■■■ — " i "". . 1 ' " 

(IF x) generates an error unless the value of eval[x] is 

true, i.e., if eval[x] causes an error or 
eval[x]*NIL, IF tyiil cause an error. 

For some editor commands, the occurrence of an error has a well defined 
meaning, i .e . , they use errors to branch on, as cond uses NIL and non-NIL. For 
example, an error condition in a location specification may simply mean "not 
this one, try the next." Thus the location specification 

(IPLUS (E (OR (NUMBERP (•## 3)) (ERROR!)) T) ) specifies the first IPLUS whoso 
second argument is a number. The IF command, by equating NIL to error, 
provides a more natural way of accomplishing the same result. Thus, an 
equivalent location specification is (IPLUS (IF (NUMBERP (## 3)))). 



because NIL as a command is a NOP, see page 9.70. 
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The IF command can also be used to select between two alternate lists of 
commands for execution. 



(IF x comsj corns^) If eval[x] is true, execute coms^; if eval[x] 

causes an error or is equal to NIL, execute 
73 



coms£ • 



For example, the command (IF (READP T) NIL (P)) will print the current 
expression provided the input buffer is empty. 

IF can also be written as: 

(IF x coms 1 ) if eval[x] is true, execute coms^; otherwise 

generate an error, 



(LP . corns) repeatedly executes corns , a list of commands, 

until an error occurs. 



For example, (LP F PRINT (N T)) will attach a T at the end of every print 
expression. (LP F PRINT (IF (## 3) NIL ( (N T)))) will attach a T at the end of 
each print expression which does not already have a second argument 



When an error occurs, LP prints n OCCURRENCES . 
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Thus IF is equivalent to (COMS (CONS (QUOTE COMSQ) (COND 
((CAR (NLSETQ (EVAL X))) COMS1) 
(T C0HS2)))). 

i.e. the form (##3) will cause an error if the edit command 3 causes an 
error, thereby selecting ( (N T) ) as the list of commands to be executed. 
The IF could also be written as (IF (CDOR (##)) NIL ( (N T))). 
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where n is the number of times corns was 
successfully executed. The edit chain is left as 
of the last complete successful execution of corns . 



(LPQ . corns) same as LP but does not print the message 

n OCCURRENCES. 

In order to prevent non-terminating loops, both LP and LPQ terminate when the 

number of iterations reaches maxloop , initially set to 30. Since the edit 

chain is left as of the last successful completion of the loop, the user can 
simply continue the LP command with REDO (Section 22). 



( SHOW , x) 



x is a list of patterns. SHOW does a LPQ printing 
all instances of the indicated expression( s ) , 
e.g. (SHOW FOO (SETQ FIE &)) will print all FOO's 
and all (SETQ FIE &)'s. Generates an error if 
there aren't any instances of the expression( s) . 



(EXAM . x) 



like SHOW except calls the editor recursively 

(via the TTY: command described on page 9.70) on 

each instance of the indicated espression( s ) so 

that the user can examine and/or change them. 



(ORR corns 



1 • 



coms n ) 



ORR begins by executing comsj , a list of commands. 
If no error occurs, ORR is finished. Otherwise, 
ORR restores the edit chain to its original value, 
and continues by executing coms 2 » etc. If none of 
the command lists execute without errors, i.e., 



76 maxloop can also be set to NIL, which is equivalent to infinity. 
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the ORR "drops off the end", ORR generates an 
error. Otherwise, the edit chain is left as of 
the completion of the first command list which 
executes without an error. 

For example, (ORR (NX) (!NX) NIL) will perform a NX, if possible, otherwise a 
!NX, if possible, otherwise do nothing. Similarly, DELETE could be written as 
(ORR (UP (1)) (BK UP (2)) (UP (: NIL))). 



9.8 Macros 



Many of the more sophisticated branching commands in the editor, such as ORR, 
IF, etc., are most often used in conjunction with edit macros. The macro 
feature permits the user to define new commands and thereby expand the editor's 

77 

repertoire. Macros are defined by using the H command. 

7 R 

(M c . corns) For c an atom, M defines c as an atomic command. 

Executing c is then the same as executing the list 
of commands corns. 



For example, (M BP BK UP P) will define BP as an atomic command which does 
three things, a BK, and UP, and a P. Macros can use commands defined by macros 
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NIL as a command list is perfectly legal, and will always execute 
successfully. Thus, making the last 'argument 1 to ORR be NIL will insure 
that the ORR never causes an error. Any other atom is treated as (atom), 
i.e., the above example could be written as (OR NX !NX NIL). 

However built in commands always take precedence over macros, i.e., the 
editor's repertoire can be expanded, but not redefined. 

If a macro is redefined, its new definition replaces its old. 



9.67 



'as well as built in commands in their definitions. For example, suppose 2 is 

defined by (H Z -1 (IF (READP T) NIL (P) )■)',' -i.e. Z does a -1, and then if 

nothing has been typed, a P. Mow we can define ZZ by 
(M ZZ -1 Z), and ZZZ by (H III -1 -i Z) or (M ZZZ -1 ZZ). 

Macros can also define list commands, i.e., commands that take arguments. 

(M (c) (arg^ arg n ) . corns) c an atom. H defines c as a list command. 

Executing (c Gj ... e^) is then performed by 
substituting e^ for arg 1? • • * 0 n for ar 9 n 
throughout corns , and then executing corns . 

For example, we could define a more general BP by (H (BP) (N) (BK N ) UP P). 
Thus, (BP 3) would perform (BK 3) , followed by an UP, followed by a P. 

A list command can be defined via a macro so as to take a fixed or indefinite 
number of ' arguments as with spread vs. nospread functions. The form given 
above specified a macro with a fixed number of arguments, as indicated by its 
argument list. If the 'argument list 1 is atomic, the command takes an 
indefinite number of arguments. 7 ^ 

(M (c) arg . corns) c, arg both atoms, defines c as a list command. 

Executing (c e^ ... e n ) is performed by 
substituting (e^ ... e n ) , i.e., cdr of the 
command, for arg throughout corns , and then 
executing corns . 

For example, the command 2ND, page 9.30, can be defined as a macro by 
(M (2ND) X (ORR ( ( LC "... X) (LG . X)))). 



Note parallelism to EXPR's and EXPR* 's. 
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Note that for all editor commands, 'built in' commands as well as commands 
defined by macros, atomic definitions and list definitions ar© completely 
independent. In other words, the existence of an atomic definition for c in no 
way affects the treatment of c when it appears as car of a list command, and 
the existence of a list definition for c in no way affects the treatment of c 
when it appears as an atom. In particular, c can be used as the name of either 
an atomic command, or a list command, or both. In the latter case, two 
entirely different definitions can be used. 

Note also that once c is defined as an atomic command via a macro definition, 
it will not be searched for when used in a location specification, unless it is 
preceded by an F. Thus (INSERT BEFORE BP) would not search for BP, but 
instead perform a BK, and UP, and a P, and then do the insertion. The 
corresponding also holds true for list commands. 

Occasionally, the user will want to employ the S command in a macro to save 
some temporary result. For example, the SW command could be defined as: 

(M (SW) (N M) (NTH N) (S F00 1) MARK 0 (NTH M) (S FIE 1) „ 
(I 1 F00) (I 1 FIE)) *° 

Since this version of SW sets foo and £ie, using SW may have undesirable side 
effects, especially when the editor was called from deep in a computation, wo 
would have to be careful to make up unique names for dummy variables used in 
edit macros, which is bothersome. Furthermore, it would be impossible to 
define a command that called itself recursively while setting free variables. 
The BIND command solves both problems. 



A more elegant definition would be: 

(M (SW) (N M) (NTH N) MARK 0 (NTH M) (S FIE 1) (I 1 (## +.1)) 
^ (I 1 FIE)), but this would still use one free variable. 
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(BIND . corns) binds' three dummy variables #1, #2, #3, 

(initialised to NIL) , and then executes the edit 
commands corns . Note that these bindings are only 
in effect while the commands are being executed, 
and that BIND can be used recursively; it will 
rebind #1, #2, and #3 each time it is invoked. 31 



Thus we could now write SW safely as: 

(M (SW (N H) (BIND (NTH N) (S #1 1) MARK 0 (NTH M) (S #2 1) 

(I 1 #1) (I 1 #2)))). 

User macros are stored on a list usermacros . The prettydef command USERMACROS 
(Section 14), is available for dumping all or selected user macros. 



9.9 Miscellaneous Commands 



NIL unless preceded by F or BF, is always a NOP. Thus 

extra right parentheses or square brackets at the 
ends of commands are ignored. 

TTY: calls the editor recursively. The user can then 

type in commands, and have them executed. The 
TTY: command is completed when the user exits from 
the lower editor, (see OK and STOP below). 



The TTY: command is extremely useful. It enables the user to set up a complex 
operation, and perform interactive attention-changing commands part way through 



81 BIND is implemented by (PROG (#1 #2 #3) (E0ITCOMS (COR COM))) where com 
corresponds to the BIND command, and editcoms is an internal editor 
function which executes a list of commands. 
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it. For example the command (HOVE 3 TO AFTER COND 3 P TTY : ) allows the user to 
interact, in effect, within the HOVE command. Thus he can verify for himself 
that the correct location has been found, or complete the specification M by 
hand." In effect, TTY: says "I'll tell you what you should do when you got 
there . " 

The TTY: command operates by printing TTY: and then calling the editor. The 
initial edit chain in the lower editor is the one that existed in the higher 
editor at the time the TTY: command was entered. Until the user exits from the 
lower editor, any attention changing commands he executes only affect the lower 
editor's edit chain. 52 When the TTY: command finishes, the lower editor*s edit 
chain becomes the edit chain of the higher editor. 

OK exits from the editor 

STOP exits from the editor with an error. Mainly for 

use in conjunction with TTY: commands that the 
user wants to abort. 

Since all of the commands in the editor are errorset protected, the user must 
exit from the editor via a command. 53 STOP provides a way of distinguishing 
between a successful and unsuccessful (from the user's standpoint) editing 
session. For example, if the user is executing (HOVE 3 TO AFTER COND TTY:), 
and he exits from the lower editor with an OK, the HOVE command will then 
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Of course, if the user performs any structure modification commands while 
under a TTY: command, these will modify the structure in both editors, 
since it is the same structure. 

Or by typing a control-D. STOP is preferred even if the user is editing at 
the evalgt level, as it will perform the necessary 'wrapup 1 to insure that 
the changes made while editing will be undoable (see Section 22). 



9.71 



complete its operation. If the user wants to abort the MOVE command, he must 
make the TTY: command generate an error. H& does this by exiting from the 
lower editor with a STOP command. In this case, the higher editor's edit chain 
will not be changed by the TTY: command. 



SAVE exits from the editor and saves the 'state of the 

edit' 06i the property list of the function or 
variable being edited under the property 
EDIT-SAVE. If the editor is called again on the 
same structure, the editing is effectively 
"continued," i.e., the edit chain, mark list, 
value of unfind and undolst are restored. 



For example: 

& p 

(NULL X) 

*F COND P 

(COND (& &) (T &)) 

«SAVE 

FOO 



«-EDITF(FOO) 
EDIT 

»P 

(COND (& &) (T &)) 
*\ P 
(NULL X) 



SAVE is necessary only if the user is editing many different expressions; an 
exit from the editor via OK always saves the state of the edit of that call to 

OA 

the editor . Whenever the editor is entered, it checks to see if it is editing 
the same expression as the last one edited. In this case, it restores the mark 



on the property list of the atom EDIT, under the property name LASTVALUE. 
OK also remprops ED IT -SAVE from the property list of the function or 
variable being edited. 
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list, the undolst , and sets unf ind to be the edit chain as of the previous exit 
from the editor. For example: 



-EDITF(FOO) 
EDIT 

(LAMBDA (X) (PROG & & LP & & & &)) 



X p 

(COND ft ft) 

* OK 

FOO 

any number of lispx inputs 
except for calls to the editor 

-EDITF(FOO) 
EDIT 

» p 

(LAMBDA (X) (PROG ft & LP- & '& & &)) 

»\ P 

(COND & ft) 



Furthermore, as a result of the history feature (section 22), if the editor is 
called on the same expression within a certain number of lispx inputs, the 
state of the edit of that expression is restored, regardless of how many other 
expressions may have been edited in the meantime. 



Namely, the size of the history list, initially 30, but it can be increased 
by the user. 
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For example: 



-EDITF(FOO) 
EDIT 



(COND (& &) (& &) (&) (T &)) 
FOO 

«- . lass than 30 lispx inputs* including editing 



«-EDITF(FOO) 

EDIT 

*\ P 

(COND (& &) (& &) (&) (T &)) 



Thus the user can always continue editing, including undoing changes from a 
previous editing session, if 

(1) No other expressions have been edited since that session ; or 

(2) That session was •sufficiently 1 recent; or 

(3) It was ended with a SAVE command. 



RAISE 



is an edit macro defined as UP followed by 
(I 1 (U-CASE ■.(## l)))y i.e. it raises to upper- 
case the current expression, or if a tail, the 
first element of the current expression. 



LOWER 



Similar to RAISE, except uses 1-case. 



Since saving takes place at exit time, intervening calls that were abortod 
via control-D or exited via STOP will not affect the editor's memory of 
this last session . 
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CAP 



First does a RAISE, and then lowers all but the 
first character, i.e. the first character is left 
capitalised. 



lVote: RAISE. LOWER, and CAP are all XOPs if the corresponding atom or string is 
already in that state. 



(RAISE x) equivalent to (I R (L-CASE x) x), i.e. changes 

every lower-case x to upper-case in the current 
expression . 



( LOWER x) similar to RAISE > except performs (I R x (L 

CASE xjj. 



Note in both (RAISE x) and (LOWER x), x is typed in in upper case. 



REPACK Permits the 'editing' of an atom or string. 



For example: 



. . . "THIS IS A LOGN STRING" ) 

REPACK 

*EDIT 

P 

(THIS 0 /. I S % A % 10 G N X S T R I N G) 

*(SW G N) 

a 0K 

"THIS IS A LONG STRING" 87 



REPACK operates by calling the editor recursively on unpack of the current 



Mote that this could also have been accomplished by (R $GN$ $NG$) or simply 
(RC GN NG). 
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expression, or if it is a list, on unpack of its first element. If the lower 
editor is exited successfully, i.e. via OK as opposed to STOP, the list of 
atoms is made into a single atom or string, which replaces the atom or string 
being 'repacked.' The new atom or string is always printed. 



(REPACK @) 



does (LC . (?) followed by REPACK, e.g. 
(REPACK THISS). 



(.5 . X) 



x is the text of a comment. ; ascends the edit 

chain looking for a 'safe' place to insert tho 

comment, e.g., in a cond clause, after a prog 

statement, etc., and inserts (*'.". x) after that 

point, if possible, otherwise before. For 

example, if the current expression is 

(FACT (SUB1 N) ) in 

[COND 

((ZEROP N) i) 
(T (ITIMES N (FACT (SUB1 N] 



(; CALL FACT RECURSIVELY) would insert 
(* CALL FACT RECURSIVELY) before the 



itimes 



expression 



88 



; does not change the edit chain, but nnf ind is 
set to where the comment was actually inserted. 



JOINC 



is used to join two neighboring COND's together, 
e.g. (COND clause j clause 2 ) followed by 



88 



If inserted after the itimes, the comment would then be (incorrectly) 
returned as the value of the cond . However, if the cond was itself a prog 
statement, and hence its value was not being used, the comment could be 
(and would be) inserted after the itimes expression* 
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(COND clause^ clause^) becomes 

(COND clause^ clause,, clause^ clause^). JOINC 

does an (F COND T) first so that you don't have to 
be at the first COND. 

(SPLITC x) splits one COND into two. x specifies the last 

clause in the first COND, e.g. (SPLITC 3) splits 
(COND clause^ clauseg clause^ clause^) into 
(COND clause 1 clause 2 ) (COND clause^ clause^). 
Uses generalized NTH command, so that x does not 
have to be a number, e.g., the user can say 
(SPLITC RETURN) , meaning split after the clause 
containing RETURN. SPLITC also does an (F COND T) 
first. 



CL Clispifies current expression. See Section 23. 

DW Dwimifies current expression. See Section 17 and 

23. 

(RESETVAR var form . corns) executes corns while var is reset to the value of 

form , and then restores var , i.e. effectively 
calls the function resetvar (Section 5). 
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9.10 UMDO 



Each command that causes structure modification automatically adds an entry to 
the front of undolst that contains the information required to restore all 
pointers that were changed by that command, 

UNDO undoes the last, i.e. most recent, structure 

modification command that has not yet beon 
undone, 5 ^ and prints the name of that command, 
e.g., MBD UNDONE. The edit chain is then exactly 
what it was before the ■undone* command had beon 
performed. ®° If there are no commands to undo, 
UNDO types NOTHING SAVED. 

! UNDO undoes all modifications performed during this 

editing session, i.e. this call to the editor. 
As each command is undone, its name is printed a 
la UNDO. If there is nothing to be undone , ! UNDO 
prints NOTHING SAVED. 



Since UNDO and 'UNDO cause structure modification, they also add an entry 
to undolst . However, UNDO and ! UNDO entries are skipped by UNDO, e.g., if 
the user performs an INSERT, and then an MBD, the first UNDO will undo the 
MBD, and the second will undo the INSERT. However, the user can also 
specify precisely which commands he wants undone by identifying the 
corresponding entry on the history list as described in Section 22. In 
this case, he can undo an UNDO command, e.g. by typing UNDO UNDO, or undo a 
!UNDO command, or undo a command other than that most recently performed. 



Undoing an event containing an I, E, or «S command will also undo the side 
effects of the evaluation(s) , e.g. undoing (I 3 ( /NCONC FOO FIE)) will not 
only restore the 3rd element but also restore FOO. Similarly, undoing an S 
command will undo the set. See discussion of UNDO in Section 22. (Note 
that if the I command was typed directly to the editor, /NCONC would 
automatically be substituted for NCONC as described in Section 22.) 
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Whenever the user continues an editing session as described on page 9.72-74, 
the undo information of the previous session is protected by inserting a 
special blip, called an undo-block, on the front of undolst . This undo-block 
will terminate the operation of a IUND0, thereby confining its effect to the 
current session, and will similarly prevent an UNDO command from operating on 
commands executed in the previous session. 

Thus, if the user enters the editor continuing a session, and immediately 
executes an UNDO or IUNDO, the editor will type BLOCKED instead of 
NOTHING SAVED. Similarly, if the user executes several commands and then undoes 
them all, another UNDO or ! UNDO will also cause BLOCKED to be typed. 

UNBLOCK removes an undo-block. If executed at a non- 

blocked state, i.e. if UNDO or ! UNDO could 
operate, types NOT BLOCKED. 

TEST adds an undo-block at the front of undolst . 

Note that TEST together with !UNDO provide a 'tentative 1 mode for editing, i.e. 
the user can perform a number of changes, and then undo all of them with a 
single !UNDO command. 
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9.11 Editdefault 



Whenever a command is not recognized, i.e., is not 'built in* or defined as a 

macro, the editor calls an internal function, editdefault , to determine what 

o 1 

action to take. If a location specification is being executed, an internal 
flag informs editdefault to treat the command as though it had been preceded by 
an F. 

If the command is a list, an attempt is made to perform spelling correction on 

op 0*5 
car of the command using editcomsl , a list of all list edit commands . If 

spelling correction is successful,^ the correct command name is rplaca ed into 

the command, and the editor continues by executing the command. 

In other words, if the user types (LP F PRINT (MBBD AND (NULL FLG) ) ) , only one 

spelling correction will be necessary to change MBBD to MBD. If spelling 

correction is not successful, an error is generated. 

If the command is atomic, the procedure followed is a little more elaborate. 



Since editdefault is part of the edit block, the user cannot advise or 
redefine it as a means of augmenting or extending the editor. However, the 
user can accomplish this via edituserfn . If the value of the variable 
edituserfn is T, editdefault calls the function edituserfn giving it the 
command as an argument. If edituserfn returns a non-NIL value, its value 
is interpreted as a single command and executed. Otherwise, the error 
correction procedure described below is performed. 



92 
93 



94 



unless dwimf lg -NIL. See Section 17 for discussion of spelling correction. 

When a macro is defined via the M command, the command name is added to 
editcomsa or editcomsl . depending on whether it is an atomic or list 
command. The prettydef command USERMACROS (Section 14), is aware of this, 
and provides for restoring editcomsa and editcomsl . 

Throughout this discussion, if the command was not typed in directly, the 
user will be asked to approve the spelling correction. See Section 17. 
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1) If the command is one of the list commands, i.e., a member of edi tcomsl , 
and there is additional input on the same terminal line, treat the ontiro 
line as a single list command. Thus, the user may omit parentheses for 
any list command typed in at the top level (provided the command is not 
also an atomic command, e.g. NX, BK). For example, 

(COND (& &) (T &)) 
«XTR 3 2] 

*MOVE TO AFTER LP 

u 

If the command is on the list editcomsl but no additional input is on the 
terminal line, an error is generated, e.g. 

« P 

(COND (& &) (T &)) 
*MOVE 

MOVE? 

If the command is on editcomsl , and not typed in directly, e.g. it appears 
as one of the commands in a LP command, the procedure is similar, with the 
rest of the command stream at that level being treated as 
"the terminal line", e.g. 

(LP F (COND (T &)) XTR 2 2). 96 

2) If the command was typed in and the first character in the command is an 8, 



The line is read using readline (Section 14). Thus the line can bo 
terminated by a square bracket, or by a carriage return not preceded by a 
space . 



Note that if the command is being executed in location context, editdef an I t 
does not get this far, e.g. (MOVE TO AFTER COND XTR 3) will search for XTR, 
not execute it. However, (MOVE TO AFTER COND (XTR 3)) will work. 
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treat the 8 as a mistyped left parenthesis, and and the rest of the line as 
the arguments to the command, e.g., 



(COND (4 4) (T 4') ) 
*8~2 (Y (RETURN Z))) 
= (-2 

(COND (Y 4) (4 4) (T &)) 



3) If the command was typed in, is the name of a function, and is followed by 
NIL or a list car of which is not an edit command, assume the user forgot 
to type E and means to apply the function to its arguments, type «E and the 
function name, and perform the indicated computation, e.g. 

*BREAK(FOO) 
-E BREAK 
(FOO) 



4) If the last character in the command is P, and the first n-1 characters 
comprise a number, assume that the user intended two commands, e.g., 

*P 

(COND (4 4) (T 4)) 

*0P 

=0 P 

(SETQ X (COND 4 4)) 



5) Attempt spelling correction using editcomsa , and if successful,^ execute 
the corrected command. 



6) Otherwise, if there is additional input on the same line, or command 
stream, spelling correct using editcomsl as a spelling list, e.g., 



97 

See footnote on page 9.81, 
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*MBBD SETQ X 
=M80 



7) Otherwise, generate an error. 



9.12 Editor Functions 



edite[ expr ; corns ;atm] 



edits an expression. Its value is the last 
element of editl[ list[expr];coms;atm]. Generates 
an error if expr is not a list. 



editl[ 1 ; corns ;atm;mess] 



no 

edit! is the editor. Its first argument is the 
edit chain, and its value is an edit chain, namely 



the value of 1 at tire time editl is exited 



99 



corns is an Optional list of commands. For 
interactive editing, corns is NIL. In this case, 
editl types EDIT and then waits for input from 
terminal. 100 All input is done with editrdtbl as a 
readtable. Exit occurs only via an OK, STOP, or 
SAVE command. 



98 



edit-eU , not edit-one. 



99 



1 is a specvar , and so can be examined or set by edit commands. For 

example, t is equivalent to (E (SETQ L ( LAST L)) T). However, the usor 

should only manipulate or examine 1 directly as a last resort, and then 
with caution. 



100 



W rcess is not NIL, editl types it instead of EDIT. For example, the TTY: 
command is essentially (SETQ L (EDITL L NIL NIL (QUOTE TTY:))). 
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If corns is not NIL, no message is typed, and each 
member of cons is treated as a command and 
executed. If an error occurs in the execution of 
one of the commands, no error message is printed, 
the rest of the commands are ignored, and odi tl 
exits with an error, i.e. the effect is the same 
as though a STOP command had been executed. If 
all commands execute successfully, edit! returns 
the current value of 1. 

atm is optional. On calls from editf , it is the 
name of the function being edited; on calls from 
editv , the name of the variable, and calls from 
editp , the atom whose property list is being 
edited. The property list of <Um is used by the 
SAVE command for saving the state of the edit. 
Thus SAVE will not save anything if atmsNIL, i.e. 
when ©diting arbitrary expressions via edite or 
edltl directly. 

editlO[ 1 ;coms;mess;editlflg]'^^ like editl except does not rebind or 

initialize the editors various state variables, 
such as lastail , unf ind , undolst , marklst , etc. 

editf [x] nlambda, nospread function for edit ing a function. 

car[x] is the name of the function,cdr[x] an 
optional list of commands. For the rest of the 
discussion, fn is car[x], and corns is cdr[x]. 



editlf lgsT is for internal use by the editor. 
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The value of editf is fn. 



In the most common case, fn is an expr, and editf simply performs 
putd[ fn ;edite[getd[fn];coms;fn]]. However, if fn is an expr by virtue of 
its being broken or advised, and 

(la) the original definition is also an expr, then the broken/advised 
definition is given to edite to be edited (since any changes there 
will also affect the original definition because all changes are 
destructive). However, a warning message is printed to alert the user 
that he must first position himself correctly before he can begin 
typing commands such as (-3 --), (N --), etc. 

(lb) the original definition is not an expr, and there is no EXPR property, 
then a warning message is printed, and the edit proceeds, e.g. the 
user may have called the editor to examine the advice for a compiled 
function. 

(1c) the original definition is not an expr, and there is an EXPR property, 
then the function is unbroken/unadvised (latter only with user's 
approval, since the user may really want to edit the advice) and 
proceed as in (2) . 

If fn is not an expr, but has an EXPR property, editf prints PROP* and 
performs edite[getp[fn;EXPR];coms;fn]. If edite returns (i.e. if the 
editing is not terminated by a STOP), and some changes were made, edi tf 
performs unsavedef [ fn], prints UNSAVED, and then does 
putd[ fn ; value -of -edite]. 

if fn is neither an expr nor has an EXPR property, and the file package 
(see section 14) 'knows 1 which file fn is contained in, the expr definition 
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of fn is automatically loaded (using loadfns ) onto its property list, and 
proceed to (2) above. ^ In addition, if fn is a member of a block (see 
section 18), the user will be asked whether he wishes the rest of the 
functions in the block to be loaded at the same time.*^ 



(4) If fn is neither an expr nor has an EXPR property, but it does have a 
definition, editf generates an fn NOT EDITABLE error. 

(5) If fn is neither defined, nor has an EXPR property, but its top level value 
is a list, editf assumes the user meant to call editv , prints =EDITV, calls 
editv and returns. Similarly, if fn has a non-NIL property list, editf 
prints =EDITP, calls editp and returns. 

(6) If fn is neither a function, nor has an EXPR property, nor a top level 
value that is a list, nor a non-NIL property list, editf attempts spelling 
correction using the spelling list userwords , l ^ and if successful, goes 
back to ( 1 ) ... 

Otherwise, editf generates an fn NOT EDITABLE error. 



i no 

Because of the existence of the file map (see section 14), this operation 
is extremely fast, essentially requiring only the time to perform the READ 
to obtain the actual definition. 

1 03 

The editor's behaviour in case (3) is controlled by the valuo of 
e di tloadfnsf lg , which is a dotted pair of two flags, the f irst of which 
(i.e. car of editloadfnsf lg ) controls the loading of the function , and the 
second the loading of the block. A value of NIL for either flag means "load 
but ask first," a value of T means "don't ask, just do it" and anything 
else means "don't ask, don ' t do it." The initial value of edi tloadf nsf lg is 
(T), meaning load the function without asking, ask about loading the block . 



Unless dwinf lgsNIL. Spelling correction is performed using the function 
misspelled? . If fn-NIL, misspelled? returns the last 'word' referenced, 
e.g. by def ineq , editf , prettyprint etc. Thus if the user defines foo and 
then types editf[ ], the editor will assume he meant foo , type =FOO, and 
then type EDIT. See Section 17. 
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If editf ultimately succeeds in finding a function to edit, i.e. does not exit 
by calling edi tv or editp , editf calls the function addspell after editing has 
been completed . Addspell 'notices' fn, i.e. sets lastword to fn, and adds fn 
to the appropriate spelling lists. If any changes were made, editf also calls 
the file package to mark the function as being changed, as described in section 
14. 106 



editv[editvx] nlambda, nospread function, similar to editf , for 

edit ing values. car[editvx] specif ies the value, 
cdr[editvx] is an optional list of commands. 

If car[editvx] is a list, it is evaluated and its value given to edite , e.g. 
EDITV((CDR (ASSOC (QUOTE F00) DICTIONARY)))). In this case, the value of editv 
is T. 

However, for most applications, car[editvx] is a variable name, i.e. atomic, as 
in EDITV(FOO). If the value of this variable is NOBINP, editv checks to see if 
it is the name of a function, and if so, assumes the user meant to call edi tf, 
prints =EDITF, calls editf and returns. Otherwise, editv attempts spelling 
correction using the list userwords . Then editv will call edite on the value 
of car[ editvx] (or the corrected spelling thereof). Thus, if the value of foo 
is NIL, and the user performs (EDITV FOO), no spelling correction will occur, 
since foo is the name of a variable in the user's system, i.e. it has a value. 



1 0 5 

Unless dwimf lg sNIL. addspell is described in Section 17. 

Even though the call to newf ile? does not occur until after the editing is 
completed, nevertheless the function is effectively marked as changed as 
soon as the first change is performed, so that even if the edit is aborted 
via control-Dp newf ile? will still be called. 

107 Unless dwimflgsNIL. Misspelled? is also called if car[editvx] is NIL, so 
that EDITVO will edit lastword. 
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However, edite will generate an error, since foo 's value is not a list, and 
hence not editable. If the user performs (EDITV F000) , where the value of f ooo 
is NOB IN 6* and foo is on the user's spelling list, the spelling corrector will 
correct FOOO to FOO. Then edite will be called on the value of foo . Note that 
this may still result in an error if the value of foo is not a list. 

When (if) edite returns, editv sets the variable to the value returned, and 
calls addspell . If any changes were made, editv also calls the file package to 
mark the variable as being changed. 

The value of editv is the name of the variable whose value was edited. 

editp[x] nlambda, nospread function, similar to editf for 

edit ing property lists. If the property list of 
car[x] is NIL, editp attempts spelling correction 
using userwords . Then editp calls edite on tho 
property list of carfx], (or the corrected 
spelling thereof). When (if) edite returns, editp 
rplacd 's car[x] with the value returned, and calls 
addspell . 

The value of editp is the atom whose property list 
was edited. 

editfns[x] nlambda, nospread function, used to perform the 

same editing operations on several functions. 
car[x] is evaluated to obtain a list of functions. 
cdr[x] is a list of edit commands, editfns maps 
down the list of functions, prints the name . of 
each function, and calls the editor (via editf ) on 
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that function. 



For example, EDITFNS(FOOFNS (R FIE FUM) ) will change every FIE to FUM in " each 
of the functions on foofns . 

The call to the editor is errorset protected, so 
that if the editing of one function causes an 
error, editfns will proceed to the next 
function. 1 * 9 

Thus in the above example, if one of the functions did not contain a FIE, the R 
command would cause an error, but editing would continue with the next 
function . 

The value of editfns is NIL. 

edit4e[pat ;x;changef lg] is the pattern match routine. Its value is T if 

pat -matches x. See page 9.21-23 for definition of 
'match 1 A 10 

Note: before each search operation in the editor begins, the entire pattern is 
scanned for atoms or strings containing alt-modes. These are replaced by 



108 i.e. the definition of editfns might be: 

[MAPC (EVAL (CAR X)) (FUNCTION (LAMBDA (Y) 
(APPLY (QUOTE EDITF) 

(CONS (PRINT Y T) (CDR X] 

In particular, if an error occurred while editing a function via its EXPR 
property, the function would not be unsaved. In other words, in the above 
example, only those functions which contained a FIE, i.e. only those 
actually changed, would be unsaved. 

110 changef lg is for internal use by the editor. 



109 
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patterns of the form (CONS (QUOTE $) (UNPACK atom/string)) for 6a, and 
(CONS (QUOTE SS) (CONS (NCHARS atom/string) (UNPACK atom/string))), for 6b. ii] 
Thus from the standpoint of edit4e , pattern type 6a is indicated by car[pot] 
being the atom S ($ is alt-mode) and pattern type 6b by car[pat] being the atom 
SS (double alt-mode). 



Therefore, if the user wishes to call edit4e directly/ he must first convert 
any patterns which contain atoms or strings ending in alt-modes to the form 
recognized by edit4e . This is done with the function editfpat « 

editf pat[pat ;f Ig] makes a copy of pat with all patterns of type 6 

112 

converted to the form expected by edit4e . 

editf indp[x;pat;flg] allows a program to use the edit find command as a 

pure predicate from outside the editor, x is an 
expression, pat a pattern. The value of editf inc lp 
is T if the command F pat would succeed, NIL 
otherwise. editf indp calls editfpat to convert 
pat to the form expected by edit4e , unless f lg=T . 
Thus, if the program is applying editf indp to 
several different expressions using tho samo 
pattern, it will be more efficient to call 
editfpat once, and then call editf indp with the 
converted pattern and f lg°T. 



In latter case, atom/string corresponds to the atom or string up to but not 
including the final two-alt-modes. In both cases, dunpack is used wherever 
possible . 

1 12 

f lg =T is used for internal use by the editor. 
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esubst[x;y;z;errorf lg;charf Ig] equivalent to performing (R y x) ii0 with z as 

the current expression, i.e. the order of 
arguments is the same as for subst . Note that v 
and/or x can employ alt-modes. The value of 
esubst is the modified 2. Generates an error*^ 
if 2 not found in 2. If errorf lg=T, also prints 
an error message of the form y ?. 

esubst is always undoable. 

changename[fn;from;to] replaces all occurrences of from by to in the 

definition of fn. If fn is an expr, changename 
performs nlsetq[esubst[fco;from;getd[fn333. If fn 
is compiled, changename searches the literals of 
fn (and all of its compiler generated 
subfunctionsJV replacing each occurrence of f rom 
with to. 116 

The value of changename is fn if at least one 
instance of from was found, otherwise NIL. 

changename is used by break and advise for changing calls to fnl to calls to 
fnl-IN-fn2. 



tig 

unless charf lg =T, in which case it is equivalent to (RC y x). See page 
9.59. 

114 of the type that never causes a break. 

1 is 

Will succeed even if from is called from fn via a linked call. In this 
case, the call will also be relinked to call to instead. 
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is available to help the user debug complex edit 
macros, or subroutine calls to the editor. If 
editracefn is set to T, the function editracefn is 
called whenever a command that was not typed in by 
the user is about to be executed, giving it that 
command as its argument. However, the TRACE and 
BREAK options described below are probably 
sufficient for most applications. 

If editracefn is set to TRACE, the name of the 
command and the current expression are printed. 
1* editracefn sBREAK, the same information is 
printed, and the editor goes into a break. The 
user can then examine the state of the editor. 

editracefn is initially NIL. 
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Index for Section 9 



(A el ... em) (edit command) 

ADDSPELL[X;SPLST;N] 

AFTER (in INSERT command) (in editor) 

AFTER (in MOVE command) (in editor) 

(B el ... em) (edit command) 

BEFORE (in INSERT command) (in editor) 

BEFORE (in HOVE command) (in editor) 

(BELOW com x) (edit command) 

(BELOW com) (edit command) 

(BF pattern T) (edit command) 

BF (edit command) 

(BI n m) (edit command) 

(BI n) (edit command) 

(BIND . corns) (edit command) 

(BK n) (n a number, edit command) 

BK (edit command) 

BLOCKED (typed by editor) 

(BO n) (edit command) 

BY (in REPLACE command) (in editor) ....... 

CAN'T - AT TOP (typed by editor) 

CAP (edit command) . 

(CHANGE <? TO ...) (edit command) 

CHANGENAMEC FN ; FROM ; TO] 

CL (edit command) 

commands that move parentheses (in editor) 

(COMS xl ... xn) (edit command) 

( COMSO . corns) (edit command) 

continuing an edit session 

control-D 

control-E 

current expression (in editor) 

DELETE (edit command) 

(DELETE . (?) (edit command) 

DESTINATION IS INSIDE EXPRESSION BEING MOVED 

(typed by editor) 

DW (edit command) 

DWIMFLG (system variable/parameter) 

(E x T) (edit command) 

(E x) (edit command) 

E (edit command) 

edit chain 



edit commands that search 

edit commands that test 

edit macros 

EDIT (typed by editor) . . 

EDITCOMSA (editor variable/parameter) 
EDITCOMSL (editor variable/parameter) 

EDITDEFAULT (in editor) .. 

EDITE[ EXPR ;COMS ;ATM] 

EDITF[ EDITFX] NL* . 

EDITF INDP[ X ; PAT ;FLG ] 

EDITFNS[X] NL* 

EDITFPAT[ PAT ;FLG] 

editing compiled functions 

EDITL[ L ; COMS ; ATM ; MESS ] . . 
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(SHOW . x) (edit command) . . 9.66 

spelling correction 9.80,82,86-87 

spelling lists ., 9.80,82,86 

(SPLITC x) (edit command) , . 9.77 

STOP (edit command) . 9.71-72,76,83-85 

structure modification commands (in editor) ..... 9.36-60 

(SURROUND 8 Hi ...) (edit command) 9.48 

(SW n m) (edit command) 9.59-60 

terminal 9.61 

TEST (edit command) 9.79 

THRU (edit command) 9.54-57 

TO (edit command) 9.54-57 

TTY: (edit command) 9.66,70-72 

TTY: (typed by editor) . . 9.71 

UNBLOCK (edit command) 9.79 

UNDO (edit command) . . 9.10,78 

undoing (in editor) 9.10,36,78-79 

UNDOLST (editor variable/parameter) 9.72,78-79,84 

UNDONE (typed by editor) 9.78 

UN FIND (editor variable/parameter) 9.25,35,41-42.46,48-51, 

.... 72-73,76,84 

UNSAVED (typed by editor) . 9.85 

UP (edit command) .... 9.12,15-16,25,43 

UPFINDFLG (editor variable/parameter) . 9.25,28,44 

USERMACROS (editor variable/parameter) 9.70 

USERMACROS (prettydef command) 9.70,80 

USERWORDS (system variable/parameter) 9.86-88 

U-CASE[X] .. 9.74 

WITH (in REPLACE command) (in editor) ... . ... 9.42 

WITH (in SURROUND command) (in editor) ...... 9.48 

(XTR . (?) (edit command) 9.45 

!NX (edit command) ...... .......... 9.19-20 

! UNDO (edit command) . 9.78 

!0 (edit command) ...... 9.18 

^[COMS] NL* . 9.29,63 

^# ( in INSERT , REPLACE, and CHANGE commands) 9.43 

S (alt-node) (in edit pattern) ... .. 9.12,21 

5 (alt-mode, in R command) (in editor) . 9.58 

SBUFS (alt-modeBUFS) (prog. asst. command) ..... . 9.7 

SS (two alt-modes) (in edit pattern) .. 9.22 

6 (in edit pattern) 9.11,21 

& (typed by editor) 9.2 

* (in MBD command) (in editor) 9.47 

* (typed by editor) 9.2 

*ANY* (in edit pattern )............... . . . .. . 9.21 

**COMMENT** (typed by editor) 9.60 

**COMMENT**FLG (prettydef variable/parameter) . .. 9.61 

( -n el ... em) (n a number, edit command) ....... 9,5,36 

-n (n a number, edit command) .................. . 9.3,17 

— (in edit pattern) ........................ 9.11,22 

- > (typed by editor) ............................ 9.58 

.. (edit command) 9.33 

... (in edit pattern) 9,22-23 

... (typed by editor) 9.13,15 

0 (edit command) 9.4-5,17 

(2ND . 0) (edit command) 9.30 

(3RD . @ ) (edit command) 9,30 
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8 (instead of left parenthesis) 9.82 

(: el ... en) (edit command) 9.14,40 

(; . x) (edit command) 9.76 

= (typed by editor) 9.12 

= E (typed by editor) 9.82 

=EDITF (typed by editor) 9.87 

= EDITP (typed by editor) 9.86 

=EDITV (typed by editor) 9.86 

= = (in edit pattern) 9.22 

? (edit command) 9.2,60 

? (typed by editor) 9.3 

0 (location specification) (in editor) 9.29 

(01 THRU) (edit command) 9.56 

(01 THRU 22) (edit command) 9.54 

(01 TO) (edit command) 9.56 

(01 TO 02) (edit command) 9.54 

(\ atom) (edit command) 9.34 

\ (edit command) 9.11,34-35,41 

\P (edit command) 9.11,35,61 

t (edit command) 9.4,18 

( *- pattern) (edit command) 9.30 

*- (edit command) 9.34 

(edit command) 9.34 
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SECTION! 10 

ATOM, STRING, ARRAY, AND STORAGE MANIPULATION 



10.1 Pnames and Atom Manipulation 

The term 'print name' (of an atom) in LISP 1.5 referred to the characters that 
were output whenever the atom was printed. Since these characters were stored 
on the atom's property list under the property PNAME, pname was used 
interchangeably with 'print name'. In INTERLISP, all pointers have pnames , 
although only literal atoms and strings have their pname explicitly stored. 

The pname of a pointer are those characters that are output when the pointer is 
printed using print , 

e.g., the pname of the atom ABCX(D 2 consists of the five characters ABC(D. The 
pname of the list (A B C) consists of the seven characters (A B C) (two of the 
characters are spaces). 

Sometimes we will have occasion to refer to the prin2-pname . 

The prin2-pname are those characters output when the corresponding pointer is 
printed using prinZ. 



except that for the purposes of the funtions described in this chapter, the 
prinl-pname of an integer is defined as though radixslO. 

% is the escape character. See Sections 2 and 14. 
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Thus the prin2- pn.ame of the atom ABCKCD is the six characters ABC%(D. 



pack[x] if x is a . list of atoms, the value of pack is a 

single atom whose 2MM is the concatenation of 
the pnames of the atoms in x, e.g. 
packCCA BC DEF G) ]«ABCDEFG . 

If the pname of the value of pack[x] is the sara© 
as that of a number, pack[x] will be that number, 
e.g. pack[(i 3.4)]«13.4,' 
pack[(l E -2)>.01. 

Although x is usually a list of atoms, it can foe a 
list of arbitrary INTERLISP pointers. Th© value 
of pack is still a single atom ^^hose pname is the 
same as the concatenation of the pnames of all the 
pointers in x e e.g. 

pack[((A B)"Cb")J - * %(A% BX)CD. 

In other words, mapc[x;prinl ] and print[pack[x]] 
always produce the same output.^ In fact, pack 
actually operates by calling print to convert the 
pointers to a stream of characters (without 
printing)- and then, makes an atom out of the 
result. 



Note that the prin2 -pnaroe also depends on what readtable is being used (see 
section 14), since this determines where %'s will be inserted. Not© also 
that the prinZ-pname of an integer depends on the setting of radix . 

4 ■ 

Except for integers when radix is other than 10, e.g. mapc[(X 9) sPRiNl 3 
produces XI 1 when radix is 8, but pack[(X 11Q)]°X9. (See footnote 1.) 
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Motet In INTERLISP-10. atoms are restricted to < 99 characters . Attempting to 
create a larger atom either via pack or by typing one in (or reading from 
a file) will cause an error, ATOM TOO LONG. 



unpack[x;f lg;rdtbl] The value of unpack is the pname of x as a list of 

characters (atoms), e.g. 
unpack[ABC] = (A B C) 
unpack["ABC(D"] = (A B C %( D) 

In other words prinl[x] and mapc[unpack[x];prinl ] 

produce the same output. 



If flcpT, the Prin2-pname of x is used, (and 
computed with respect to rdtbl ) e.g. 
unpack[ f, ABC(D H ;T]« (X M A B C X( 0 % M ). 



Note: unpack[x] performs n conses, where n is the number of characters in the 
pname of x. "V 



dunpack[x;scratchlist ;f lgsrdtbl] a destructive version of unpack that does not 

perform any conses but instead uses scratchlist to 
make a list equal to unpack[x;f lg]. If the p-name 
is too long to fit in scratchlist , dunpack calls 
unpack and returns unpack[x;f lg]. Gives an error 
if scratchlist is not a list. 



nchars[x;f lg;rdtbl] number of characters in pname of x. g If f lg=T, the 



There are no special f character-atoms 1 in INTERLISP, i.e. an atom 
consisting of a single character is the same as any other atom. 

Both nthchar and nchars work much faster on objects that actually have an 
internal representation of their pname, i.e. literal atoms and strings, 
than they do on numbers and lists, as they do not have to simulate 
printing. 



10.3 



prln2-pname is used. E.g. nchars[ "ABC" 3=3, 
■nchar's["ABC* ;T]*5-. 

nthchar[x;n ;f lg;rdtbl] Value is nth character of pname of x. Equivalent 

to car[nth[unpack[x;f lg];n]] but faster and does 
no conses. n can be negative, in which case 
counts from end of pname » e.g. -1 refers to the 
last character, -2 next to last, etc. If n is 
greater than the number of characters in the 
pname, or less than minus that number, or 0, the 
value of nthchar is NIL. 

packc[x] like pack except x is a list of character codes/ 

e.g. packc[(70 79 79)]=FOO. 

chcon[x;f lg ;rdtbl] like unpack , except returns the pname of x as a 

list of character codes, e.g. chcon[FOO] = (70 79 
79). If £12= T, the prin2- pname is used. 

chconl[x] returns character code of first character of pname 

of x, e.g. chconl[FOO] = 70. Thus chcon[x] could 
be written as mapcar[unpack[x];chconl ]. 

dchcon[x;scratchlist ;f lg;rdtbl] similar to dunpack 

character[n] n is a character code. Value is the atom having 

the corresponding single character as its pname , 8 

7 ..INTERLISP-10 uses ASCII code. 

8 See footnote 2. 
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e.g. character^ 70] ■ F. Thus, unpack[x] could bo 
written as mapcar[chcon[x];character], 

fcharacter[n] fast version of character that compiles open. 

gensym[char] Generates a new atom of the form xnnnn, where 

x=char (or A if char is NIL) in which each of the 
n's is a digit. Thus, the first one generated is 
A0001, the second A0002, etc. gensym provides a 
way of generating new atoms for various uses 
within the system. The value of gennum , initially 
10000, determines the next gensym , e.g. if gennum 
is set to 10023, gensym[ ]«A0024 . 

The term gensym is used to indicate an atom that was produced by the Junction 
gensym . Atoms generated by gensym are the same as any other literal atomsi 
they have property lists, and can be given function definitions . Note that the 
atoms are not guaranteed to be new. 

For example, if the user has previously created A0012, either by typing it in, 
or vi$ pack or gensym itself, when gennum gets to 10011, the next value 
returned by gensym will be the A0012 already in existence. 

mapatoms[fn] Applies fn to every literal atom in the system, 

e.g. mapa toms[ ( LAMBDA( X ) ( AND ( SUBRP X)( PRINT X)))] 
will print every subr. Value of mapatoms is NIL. 

10.2 String Functions 

stringp[x] Is x if x a string, NIL otherwise. Note: if x is 

a string, nlistp[x] is T, but atom[x] is NIL. 
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strequal[x;y] Is x if x and y are both strings and equal, i.e. 

print the same, otherwise NIL. Equal uses 
strequal . Note that strings may be equal without 
being ££. 

mkstring[x] Value is string corresponding to print of x. 

rstring[] Reads a string - see Section 14. 

substring[x;n;m] Value is the substring of x consisting of the nth 

thru mth characters of x. If m is NIL, the 
substring is the nth character of x thru the end 
of x^ n and m can be negative numbers, as with 
nthchar . Returns NIL if the substring is not well 
defined, e.g. n or m > hchars[x] or 
< minus{nchars[x]J or n corresponds to a character 
in x to the right of the character indicated by m. 

If x is not a string, equivalent to 
substring[mkstring[x];n ;m], except substring does 
not have to actually make the string if x is a 
literal atorn.^ For example, 
substring[(A B C);4;6]«"B C". 

gnc[x] get next character of string x. Returns the next 

character of the string, (as an atom), and removes 
the character from the string. Returns NIL if x 
is the null string. If x isn't a string, a string 



See string storage section that follows. 
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is made. Used for sequential access to characters 
of a string. 

Note that if x is a substring of jr, gnc[x] doos 
not remove the character from i.e. gnc doesn't 
physically change the string of characters, just 
the pointer and the byte count. 



glc[x] gets last character of string x. Above remarks 

about gnc also supply to glc . 

concat[X| ;x 2 ; . . . ;x n ] lambda nospread function. Concatenates (copies 

of) any number of strings. The arguments are 
transformed to strings if they aren't strings. 
Value is the new string, e.g. 

concat[ M ABC" ;DEF ; "GUI" ] * ABCPEFGHI M • The value 
of concat[ ] is the null string, Hil . 



rplstring[x;n;y] Replace characters of string x beginning at 

character n with string jr v n may be positive or 
negative. x and jj are converted to strings if 
they aren't already. Characters are smashed into 
(converted) x. Returns new x. Error if there is 
not enough room in x for i.e. the new string 
would be longer than the original. 11 Note that if 
x is a substring of 2, 2 will also be modified by 
the action of rplstring . 



10 
11 



See string storage section that follows. 

If x was not a string, x will already have been partially modified since 
rplstring does not know~whether £ will •fit 1 without actually attempting 
the transfer. 
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mkatom[x] Creates an atom whose pname is the same as that of 

the string x or if x isn't a string, the same as 
that of mkstringCx], e.g. mkatomC ( A B C) ] is the 
atom */.(AX B% C%). In INTERLISP-10, if the atom 
would have > 99 characters, causes an error, ATOM 
TOO LONG. 

Searching Strings 

strpos is a function for searching one string looking for another. Roughly it 
corresponds to member , except that it returns a character position number 
instead of a tail. This number can then be given to substring or utilized in 
other calls to strpos . , 

strposC x;y; start ; skip ;anchor; tail] 

x and x are both strings (or else they are 
converted automatically). Searches £ beginning at 
character number start , (or else 1 if start is 
NIL) and looks for a sequence of characters equal 
to x- If a match is found, the corresponding 
character position is returned, otherwise NIL, 
e.g. ,. 

strposC "ABC" , "XYZABCDEF" >4 
strpos[ H ABC H , "XYZABCDEF" ; 5 ]=NIL 
strpos[ "ABC" , "XYZABCDEFABC" ; 5]=10 

skip can be used to specify a character in x that 
matches any character in e.g. 
strposC "A&C&" ; "XYZABCDEF" ;NIL ;&]*4 
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If anchor is T, strpos compares x with tho 
characters beginning at position start , or 1. If 
that comparison fails, strpos returns NIL without 
searching any further down Thus it can be used 
to compare one string with some portion of another 
string, e.g. 

strpos[ l, ABC ,, 5 ,, XYZABCDEF ,, ;NIL;NIL;T]=NIL 
strpos[ ,, ABC ,, ; M XYZABC0EF ,, ;4;NIL;T]=:4 



Finally, if tail is T, the value returned by 
strpos if successful is not the starting position 
of the sequence of characters corresponding to x; 
but the position of the first character after 
that, i.e. starting point plus nchars[x] e.g. 
strpos[ "ABC"; "XYZABCDEFABC" ;NIL;NIL;NIL;T]=7. 
Note that strpos[ M A tt ; M A" ;NIL;NIL;NIL;T]«2 , • even 
though M A M has only one character. 



Example Problem 

Given the strings x> Xi and 2, write a function foo that will make a string 
corresponding to that portion of x between % and 2, e.g. 
foo["NOW IS THE TIME FOR ALL GOOD MEN" ; M IS" ; "FOR* ] is M THE TIME w . 

Solution: 

(FOO 

[LAMBDA (X Y Z) 

(AND (SETQ Y (STRPOS Y X NIL NIL NIL T)) 
(SETQ Z (STRPOS Z X Y)) 
(SUBSTRING X Y (SUB1 Z]) 
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strposl[a;str ;start;neg] str is a string (or else it is converted 

automatically to a string),, a is a list of 

IP 

characters or character codes. strposl 
searches str beginning at character number start 
(or else 1 if startsNlL) for one of the characters 
in a. If one is found, strposl returns as its 
value the corresponding character position, 
otherwise NIL. E.g., strposl[ ( A B C ) ; "XYZBCD" >4 . 
If negsT, strposl searches for a character not on 
a, e.g., strposl{(A B C); "ABCDEF" ;NIL;T]«4 . 

If a is an array, it is treated as a bit table. 
The bits of (ELT A 1) correspond to character 
codes 0 to 43Q, of (ELT A 2) to codes 44Q to 107Q, 
etc. Thus an array whose first element was 17Q 
would be equivalent to a list (40Q 410 420 430) or 
(%_ ! %" #). 

If a is not a bit table (array), strposl first converts it to a bit table using 
makebittable described below. If strposl is to be called frequently wi.th the 
same list of characters, a considerable savings can be achieved by converting 
the list to a bit table once, and then passing the bit table to strposl as its 
first argument. 

makebittable[ 1 ;neg;a] makes a bit table suitable for use by strposl . 1 

and necj are as for strposl . If a is not a 
suitable array, makebittable will create an array 



If any element of a is a number, it is assumed to be a character codo . 
Otherwise, it is converted to a character code via chconl . Therefore, it 
is more efficient to call strposl with a a list of character codes . 
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and return that as Its value. Otherwise it uses 
(and changes) a. 

Note: if neg =T, strposl must call makebittable whether a is a list or an 
array. To obtain bit table efficiency with neg sT, makebittable should bo 
called with neg =T, to construct the "inverted" table, and the resulting table 
(array) should be given to strposl with negsNIL. 

String Storage 

A string is stored in 2 parts; the characters of the string, and a pointer to 
the characters. The pointer, or 'string pointer', indicates the byte at which 
the string begins and the length of the string. It occupies one word of 
storage. In INITERLISP-10, the characters of the string are stored five 
characters to a word in a portion of the address space devoted exclusively to 
storing characters. 

Since the internal pname of literal atoms also consists of a pointer to the 
beginning of a string of characters and a byte count, conversion betweon 
literal atoms and strings does not require any additional storage for the 
characters of the pname , although one cell is required for the string 
pointer. 

When the conversion is done internally, e.g. as in substring , strpos . or 
strposl , no additional storage is required for using literal atoms instead of 
strings . 



Except when the string is to be smashed by rplstring. In this case, its 
characters must be copied to avoid smashing the pname of the atom. 
rplstring automatically performs this operation. 
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The use of storage by the basic string 

mkstring[x] x string 

x literal atom 
other 

substring[x;n ;m] x string 

x literal atom 
other 

gnc[x] and glc[x] x string 

other 

concat[Xj ;x 2 ; . . .x n ] args any type 
rplstring[x;n;y] x string 



x other 
y any type 



functions is given below: 

no space 
new pointer 

new characters and pointer 

new pointer 
new pointer 

new characters and pointer 

no space, pointer is modified 

like mkstring , but doesn't make much 

sense 

new characters for whole now 
string, one new pointer 

no new space unless characters are in 
pname space (as result of 
mkstring[atom]) in which case x is 
quietly copied to string space 
new pointer and characters 
type of y doesn't matter 
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10,3 Array Functions 



Space for arrays and compiled code are both allocated out of a common array 
space. Arrays pf pointers and unboxed numbers may be manipulated by tho 
following functions: 

array[n;p;v] This function allocates a block of n+2 words, of 

which the first two are header information. The 
next p < n are cells which will contain unboxed 
numbers, and are initialized to unboxed 0. The 
last n-p > 0 cells will contain pointers 
initialized with v, i.e., both car and cdr are 
available for storing information, and each 
initially contain v. If g is NIL, 0 is used 
(i.e., an array containing all INTERLISP 
pointers). The value of array is the array, also 
called an array pointer. If sufficient space is 
not available for the array, a garbage collection 
of array space, GC: 1, is initiated. If this is 
unsuccessful in obtaining sufficient space, an 
error is generated, ARRAYS FULL. 

Array-pointers print as where n is the octal representation oj the pointer. 
Note that ^n will be read as a literal atom, and not an array pointer . 

swparray[n ;p;x] like array but allocates a swappable array. (See «• 

section 3, ) ♦ 

arraysize[a] Returns the size of array a. Generates an error, 

ARG NOT ARRAY, if a is not an array. 
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arrayp[x] Value is x if x is an array pointer otherwise NIL. 

No check is made to ensure that x actually 
addresses the beginning of an array. 

swparrayp[x] Value is x if x is a swappable array, NIL 

otherwise . 



elt[a;n] Value is nth element of the array a 14 elt 

generates an error, ARG NOT ARRAY, 1f a is not tho 
beginning of an array. ^ 5 If n corresponds to tho 
unboxed region of a, the value of elt 1s the full 
36 bit word, as a boxed Integer. If n corresponds 
to the pointer region of a, the value of elt is 
the car half of the corresponding element. 



setat a ;n ;v] sets the nth element of the array a. Generates an 

error, ARG NOT ARRAY, if a is not the beginning 
of an array. If n corresponds to the unboxed 
region of a, v must be a number, and is unboxed 
and stored as a full 36 bit word into the nth 
element of a. If n corresponds to the pointer 
region of a, v replaces the car half of the nth 
element. The value of seta is v. 

A'ote that seta and el t are always inverse operations . 
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elt[a ; 1 ] is the first element of the array (actually corresponds to the 3rd 
cell because of the 2 word header). 

arrayp is true for pointers into the middle of arrays , but elt and seta 
must be given a pointer to the beginning of an array, i.e., a value of 
array . 
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eltd[a;n] same as Bit for unboxed region of a , but returns 

cdr half of nth element,, if n corresponds to the 
pointer region of a. 



setd[a;n;v] same as seta for unboxed region of a, but sets cdr 

half of nth element, if n corresponds to the 
pointer region of a. The value of setd is v. 



In other words, eltd and setd are always inverse operations. 



10.4 Storage Functions 



reclaim[n] Initiates a garbage collection of type n . Value 

°' reclaim is number of words available Tfor that 
type) after the collection. 



Garbage col Lections . whether invoked directly by the user or indirectly by need 
for storage, do not confine their activity solely to the data type for which 
they were called, but automatically collect some or all of the other types (sec 
Section 3) . 



ntyp[x] Value is type number for the data type of 

INTERLISP pointer x, e.g. ntyp[ (A . B)] is 8, the 
type number for lists. Thus GC: 8 indicates a 
garbage collection of list words. 
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type 



number 



arrays, compiled code 
stack positions 
swapped array handles 
list words 
atoms 

floating point numbers 
large integers 
small integers 
string pointers 
pname storage 
string storage 



2 
4 
8 
12 
16 
18 
20 
24 
28 
30 
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typep[x;n] 



eq[ntyptx];n] 



gcgag[message] 



affects messages printed 



by garbage collector. If 



message sT, its standard setting, whenever a 
garbage collection is begun, GC: is printed, 
followed by the type number. When the garbage 
collection is complete, two numbers are printed 
the number of words collected for that type, and 
the total number of words available for that type, 
i.e. allocated but not necessarily currently in 
use (see minfs below) . 

Example: 
-RECLAIM(18) 
GC: 18 

511, 3071 FREE WORDS 
3071 

-RECLAXM(12) 
GC: 12 

1020, 1020 FREE WORDS 
1020 
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New user data types (see section 23) are assigned type numbers beginning 
with 31 . 
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If message=NIL, no garbage collection message is 
printed, either on entering or leaving the garbage 
collector. 

If message is a list, car of message is printed 
(using print ) when the garbage collection is 
begun, and cdr is printed when the collection is 
finished. If message is an atom or string, 
message is printed when the garbage collection is 
begun, and nothing is printed when the collection 
finishes. 

The value of gcgag is its previous setting 

minf s[n ;typ] Sets the minimum amount of free storage which will 

be maintained by the garbage collector for data 
types of type number typ. If, after any garbage 
collection for that type, fewer than n free words 
are present, sufficient storage will be added (in 
512 word chunks) to raise the level to n. 

If typ =NIL, 8 is used, i.e. the minfs refers to 
list words. 

If n=NIL, minfs returns the current minfs setting 
for the corresponding type. 

A minfs setting can also be changed dynamically, even during a garbage 
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17 

collection, by typing control-S followed by a number, followed by a period. 
If the control-S was typed during a garbage collection, the number is the new 
minf s setting for the type being collected, otherwise for type 8, i.e. list 
words. 



Note*. A garbage collection of a 'related' type may also cause more storage to 
be assigned to that type. See discussion of garbage collector algorithm. 
Section 3. 



storage[ fig] 



Prints amount of storage (by type number) used by 
and assigned to the user, e.g. 



-STORAGE*) 



TYPE 


USED 


ASSIGNED 


1 


8927 


12288 


2 


5120 


4120 


4 


23 


512 


8 


6037 


15360 


12 


2169 


3584 


16 


0 


512 


18 


173 


2048 


24 


110 


2048 


28 


802 


2048 


30 


312 


512 


SUM 


23673 


44032 



If f Ig aT, includes storage used by and assigned to 
the system. Value is NIL. 



gctrp[n ] 



garbage collection trag. Causes a (simulated) 
control-H interrupt when the number of free list 
words (type 8) remaining equals n, i.e. when a 
garbage collection would occur in n more conses. 



When the control-S is typed, INTERLISP immediately clears and saves the 
input buffer, rings the bell, and waits for input, which is terminated by 
any non-number. The input buffer is then restored, and the program 
continues. If the input was terminated by other than a period, it is 
ignored. 
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The message GCTRP is printed, the function 

interrupt (Section 16) is called, and a break. 

occurs. Note that by advising (Section 19) 

interrupt the user can program the handling of a 

1 8 

gctrp instead of going into a break. 

Value of gctrp is its last setting. 

gctrp[-l] will •disable 1 a previous gctrp since 
there are never -1 free list words. gctrp is 
initialized this way. 

gctrp[] returns number of list words left, i.e. 
number of conses until next type 8 garbage 
collection, see Section 21. 

conscountCn] conscount[ ] returns number of conses since 

INTERLISP started up. If n is not NIL, resets 
conscount to n. 

closer[a;x] Stores x into memory location a. Both x and a 

must be numbers. 

openr[a] Value is the number in memory location a, i.e. 

boxed. 



For gctrp interrupts, interrupt is called with intype (its third argument) 
equal to 3. If the user does not want to go into a break, the advice 
should still allow interrupt to be entered, but first set intype to -1. 
This will cause interrupt to "quietly" go away by calling the function that 
was interrupted. The advice should not exit interrupt via return , as in 
this case the function that was about to be called when the interrupt 
occurred would not be called. 
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pnames . 10. 1-5, 11 
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SECTION 11 
FUNCTIONS WITH FUNCTIONAL ARGUMENTS 



As in all LISP 1.5 Systems, arguments can be passed which can then be used as 
functions. However, since car of a form is never evaluated, apply or apply * 
must be used to call the function specified by the value of the functional 
argument . 

Functions which use functional arguments should use variables with obscure 
names to avoid possible conflict with variables that are used by the functional 
argument. For example, all system functions standardly use variable names 
consisting of the function name concatenated with x or fn, e.g. mapx . Note 
that by specifying the free variables used in a functional argument as tho 
second argument to function , thereby using the INTERLISP FUNARG feature, the 
user can be sure of no clash. 

function[x;y] is an nlambda function. If pNIL, the value of 

function is identical to quote , for example, 
(MAPC LST (FUNCTION PRINT) ) will cause mapc to be 
called with two arguments the value of 1st and 
PRINT. Similarly, 

(HAPCAR LST (FUNCTION(LAMBDA( Z) (LIST (CAR Z))))) 
will cause mapcar to be called with the value of 
1st and (LAMBDA (Z) (LIST (CAR Z))). When 
compiled, function will cause code to be compiled 
for x; quote will not. Thus 
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(MAPCAR LST (QUOTE (LAMBDA --))) will cause ma pear 
to be called with the value of 1st and tho 
expression (LAMBDA --). The functional argument 
will therefore still be interpreted. The 
corresponding expression using function will cause 
a dummy function to be created with definition 
(LAMBDA --), and then compiled, mapcar would then 
be called with the value of 1st and the name of 
the dummy function. See Section 18. 

If x is not NIL, it is a list of variables that 
are (presumably) used freely by x. In this case, 
the value of function is an expression of the form 
(FUNARG x array), where array contains the 
variable bindings for those variables on j£. 
Funarg is described on page 11.5-7. 

map[mapx;mapfnl ;mapfn2] If mapfn2 is NIL, map applies the function mapfnl 

to successive tails of the list mapx * That is, 
first it computes mapf nl[mapx], and then 
mapfnl[cdr[mapx]], etc., until mapx is exhausted.* 
If mapfn2 is provided, mapfn2[mapx] is used 
instead of cdr[mapx] for the next call for mapfnl , 
e.g., if mapfn2 were eddr, alternate elements of 
the list would be skipped. 

The value of mag is NIL. map compiles open. 



i.e., becomes a non-list. 
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mapc[mapx;mapfnl ;mapfn2] Identical to mag, except that mapfnl[car[mapx]] is 

computed at each iteration instead of 
mapfnl[mapx], i.e., mapc works on elements, map on 
tails. The value of mapc is NIL. mapc compiles 
open. 



maplist[mapx;mapfnl ;mapfn2] successively computes the same values that map 

would compute; and returns a list consisting of 
those values, maplist compiles open. 



mapcar[mapx;mapfnl ;mapfn2] 



computes the same values that mapc would compute, 
and returns a list consisting of those values, 
e.g. mapcar[x;FNTYP] is a list of fntyps for each 
element on x. mapcar compiles open. 



mapcon[mapx;mapfnl ;mapfn2] Computes the same values as map and maplist but 

nconcs these values to form a list which it 
returns, mapcon compiles open. 

rnapconc[mapx;mapfnl ;mapfn2] Computes the same values as mapc and mapcar , but 

nconcs the values to form a list which it returns, 
mapconc compiles open. 



Note that mapcar creates a new list which is a mapping of the old list in that 
each element of the new list is the result of applying a function to the 
corresponding element on the original list, mapconc is used when there are a 
variable number of elements (including none) to be inserted at each iteration, 
e.g. mapconc[X ; ( LAMBDA (Y) (AND Y (LIST Y))>] will make a list consisting of x 
with all NILs removed, mapconc[X ;( LAMBDA (Y) (AND (LISTP Y) Y))] will make a 
linear list consisting of all the lists on x, e.g. if applied to 
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((A B) C (D E F) (6) H I) will yield (A B D E F G), 2 



subsettmapximapfnismapfnZ] applies mapfnl to elements of mapx and returns a 

list of those elements for which this application 
is non-NIL, e.g. , 

subset[(A BSC 4);NUMBERP] * (3 4). 

mapfn2 plays the same role as with map , mape , et 

al. subset compiles open. 

flu*p2c[mapx;mapy;mapfnl ;mapfn2] Identical to mapc except mapfnl is a function 

of two arguments, and mapfnl[car[mapx];car[mapy]] 
is computed at each interation. Terminates when 
either mapx or mapy are exhausted. 

map2car[mapx;mapy;mapfni;mapfn2] Identical to mapcar except mapfnl is a 

function of two arguments and 

mapfnl[car[mapx];car[mapy]] is used to assemble 
the new list. Terminates when either mapx or mapy 
is exhausted. 

Note: CUSP (Section 23> provides a more general and complete facility for 
expressing iterative statements, e.g. (FOR X IN Y COLLECT (CADR X) WHEN 
( NUMBERP (CAR X)) UNTIL (NULL X)). 



Note that since mapconc uses nconc to string the corresponding lists 
together, in this example, the original list will be clobbered, i.e. it 
would now be ( (A B D E F G) C (D E F G) (G) H I). If this is an undesirable 
side effect, the functional argument to mapconc should return instead a top 
level copy, e.g. in this case, use (AND (LISTP Y) (APPEND Y) ) . 



mapfn2 is still a function of one argument, and is applied twice on each 
iteration; mapfn2[mapx] gives the new mapx , mapfn2[mapy] the new mapy . cdr 
is used if mapfn2 is not supplied, i.e., is NIL. 
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maprint[ 1st ; file; left ; right ; sep; pfn;lispxprintf Ig] 

is a general printing function. It cycles through 
1st applying £fn (or print if £fn not given) to 
each element of 1st. Between each application, 
maprint performs prinl of se£, or H " if sep =NIL . 
If left is given, it is printed (using prinl ) 
initially; if right is given it is printed (using 
prinl ) at the end. 

For example, maprint[x;NIL;%( ;%) ] is equivalent to 
prinl for lists. To print a list with commas 
between each element and a final * . • one could use 
maprint[x;T;NIL;%. ]. 

If lispxprintf Ig » T, lispxprinl is used for prinl 
(see Section 22) . 

Mapdl, searchpdl See Section 12. 

mapatoms See Section 5. 

every, some, notevery, notany See Section 5. 

Funarg 

function is a function of two arguments, x, a function, and y a list of 
variables used freely by x. If # is not NIL, the value of function is an 
expression of the form (FUNARG x array), where array contains the bindings of 
the variables on % at the time the call to function was evaluated. funarg is 
not a function itself. Like LAMBDA and NLAMBDA, it has meaning and is 
specially recognized by INTERLISP only in the context of applying a function to 
arguments. In other words, the expression (FUNARG x array) is used exactly 
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like a function. When a funarg is applied, the stack is modified so that tho 
bindings contained in the array will be in force when x, the function, is 
called. 5 

For example, suppose a program wished to compute (FOO X (FUNCTION FIE)), and 
f ie used y and z as free variables. If foo rebound £ and 2, fie would obtain 
the rebound values when it was applied from inside of foo . By evaluating 
instead (FOO X (FUNCTION FIE ( Y Z) ))■»■. foo would be called with 
(FUNARG FIE array) as its second argument, where array contained the bindings 
of 2 and 2 (at the time foo was called). Thus when fie was applied from inside 
of foo , it would , see l the original values of y and 2. 

However, funarg is more than just a way of circumventing the clashing of 
variables. For example, a funarg expression can be returned as the value of a 
computation, and then used 'higher up 1 , e.g., when the bindings of the 
variables contained in array were no longer on the stack. Furthermore, if tho 
function in a funarg expression seti any of the variables contained in t^e 
array, the array itself (and only the array) will be changed. For example, 
suppose foo is defined as 

(LAMBDA (LST FN) (PROG (Y Z) (SETQ Y &) (SETQ Z &) ... (MAPC LIST FN) ...)) 
and (FOO X (FUNCTION FIE (Y Z))) is evaluated. If one application of fie (by 
the mapc in foo ) changes £ and 2, then the next application of fie will obtain 
the changed values of % and 2 resulting from the previous application of fie , 
since both applications of fie come from the exact same funarg object, and 
hence use the exact same array. The bindings of £ and 2 bound inside of foo , 

LAMBDA, NLAMBDA, and FUNARG expressions are sometimes called 'function 
objects' to distinguish them from functions, i.e., literal atoms which have 
function definitions. 

5 The implementation of funarg is described in Section 12, 
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and the bindings of £ and z above foo would not be affected. In other words, 
the variable bindings contained in array are a part of the function objoct, 
i.e., the funarg carries its environment with it. 

Thus by creating a funarg expression with function , a program can create a 
function object which has updateable binding(s) associated with the objoct 
which last between calls to it, but are only accessible through that instance 
of the function. For example, using the funarg device, a program could 
maintain two different instances of the same random number generator in 
different states, and run them independently. 

Example 

If foo is defined as (LAMBDA (X) (COND ((ZEROP A) X) (T (MINUS X))) and fie as 
(LAMBDA NIL (PROG (A) (SETQ A 2) (RETURN (FUNCTION FOO)))). then if we perform 
(SETQ A O), (SETQ FUM (FIE)), the value of fum is FOO, and the value of 
( APPLY* FUM 3) is 3, because the value of A at the time foo is called is 0. 

However if fie were defined instead as 

(LAMBDA NIL (PROG (A) (SETQ A 2) (RETURN (FUNCTION FOO (A))))), the value of 
fum would be (FUNARG FOO array) and so the value of (APPLY* FUM 3) would be -3, 
because the value of A seen by foo is the value A had when the funarg was 
created inside of fie, i.e. 2. 
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SECTION 12 

VARIABLE BINDINGS AND PUSH DOWN LIST FUNCTIONS 1 



A number of schemes have been used in different implementations of LISP for 
storing the values of variables. These include: 



1. Storing values on an association list paired with the variable names. 



2. Storing values on the property list of the atom which is the name of 
the variable. 



3. Storing values in a special value cell associated with the atom name, 
putting old values on a pushdown list, and restoring these values when 
exiting from a function. 



4. Storing values on a pushdown list. 



The first three schemes all have the property that values are scattered 



As of the date of this revision (October 1974), a major effort at BBN is 
nearing completion to implement in INTERLISP-10 the stack implementation 
for multiple environments (spaghetti stacks) described in [Bob3]. When 
this is completed, much of the material in this section will be obsolete. 
However, our design philosophy of making the stack accessible to user 
programs will, if anything, be generalized and improved upon. In addition, 
the stack manipulating primitives will be defined in a less 
system-dependent way, so that user programs which reference the stack* will 
be more readily transportable between different implementations of 
INTERLISP. 
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throughout list structure space, and, in general, in a paging environment would 
require references to many pages to determine the value of a variable. This 
would be very undesirable in our system. In order to avoid this scattering, 
and possibly excessive secondary storage references, we utilize a variation on 
the fourth standard scheme, usually only used for transmitting values of 
arguments to compiled functions; that is, we place these values on the pushdown 
list. But since we want a compatible interpreter and compiler, the variable 
names must also be kept. The pushdown list thus contains pairs, each 
consisting of a variable name and its value. In INTERLISP-10, each pair 
occupies one word or 'slot' on the pushdown list, with the name in one half, 
and the value in the other. The interpreter gets the value of a variable by 
searching back up the pushdown list looking for a 'slot 1 containing the name of 
that variable. 

One advantage of this scheme is that the current top of the pushdown stack is 
usually in core, and thus secondary storage references are rarely required to 
find the value of a variable. Free variables work automatically in a way 
similar to the association list scheme, except that within a function, a free 
variable may be searched for only once (e.g. in compiled functions). 

An additional advantage of this scheme is that it is completely compatible with 
compiled functions which pick up their arguments on the pushdown list from 
known positions, instead of doing a search. Since our compiled functions save 
the names of their arguments,^ although they do not use them to reference 



Also called the stack. 

Currently, compiled functions save the names of their arguments on the 
stack, the same as do interpreted functions. We are currently considering 
a scheme in INTERLISP-10 whereby the names of variables bound by compiled 
functions would not be stored on the stack, but would instead be computable 
from the compiled definition. However, this is an implementation detail. 
The essential point is that there be a way to associate a name with the 
value for variables bound by either interpreted or compiled functions. 
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variables, free variables can be used between compiled and interpreted 
functions with no special declarations necessary. The names are also very 
useful in debugging, for they make possible a complete symbolic backtrace in 
case of error. Thus this technique, for a small extra overhead, minimizes 
secondary storage references, provides symbolic debugging information, and 
allows completely free mixing of compiled and interpreted routines. 

There are (currently) 4 three pushdown lists used in INTERLISP-10 : the first is 
called the parameter pushdown list, and contains pairs of variable names and 
values, and temporary storage of pointers; the second is called the control 
pushdown list, and contains function returns and other control information; and 
the third is called the number stack and is used for storing temporary partial 
results of numeric operations. 

However, it is more convenient for the user to consider the push-down list as a 
single "list" containing the names of functions that have been entered but not 
yet exited, and the names and values of the corresponding variables . The 
multiplicity of pushdown lists in the actual implementation is for efficiency 
of operation only. 

The Push-Down List and the Interpreter 

In addition to the names and values of arguments for functions, information 
regarding partially-evaluated expressions is kept on the push-down list. For 
example, consider the following definition of the function fact (intentionally 
faulty) : 



this will change in the spaghetti system. 
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(FACT 

[ LAMBDA (N) 
(COND 

((ZEROP N) 
L) 

(T (ITIMES N (FACT (SUB1 N]) 

In evaluating the form (FACT 1), as soon as fact is entered/ the interpreter 
begins evaluating the implicit progn following the LAMBDA (see Section 4). The 
first function entered in this process is cond . cond begins to process its 
list of clauses. After calling zerop and getting a NIL value, cond proceeds to 
the next clause and evaluates T. Since T is true, the evaluation of the 
implicit progn that is the consequent of the T clause is begun (see Section 4). 
This requires calling the function itimes . However before itimes can be 
called, its arguments must be evaluated. The first argument is evaluated by 
searching the stack for the last binding of N; the second involves a recursive 
call to fact , and another implicit progn , etc. 

Note that at each stage of this process, some portion of an expression has been 
evaluated, and another is awaiting evaluation . The output below illustrates 
this by showing the state of the push-down list at the point in the computation 
of (FACT 1) when the unbound atom L is reached. 
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-FACT( 1 ) 

u.b.a. L {1n FACT} 1n ((ZEROP N) L) 

(L BROKEN) 

:BTV! 

*FORM* ( BREAK 1 L T L NIL ((COND ((ZEROP N) L) (T (ITIMES N (FACT 
(SUB1 N ))))))) 
-TAIL* (L) 

*ARG1* (((ZEROP N) L) (T (ITIMES N (FACT (SUB1 N ) ) ) ) ) 
COND 

"FORM* (COND ((ZEROP N) L) (T (ITIMES N (FACT (SUB1 N))))) 
"TAIL* ((COND ((ZEROP N) L) (T (ITIMES N (FACT (SUB1 N) ) ) ) ) ) 

N 0 
FACT 

"FORM* (FACT (SUB1 N)) 
*FN* ITIMES 

"TAIL* ((FACT (SUB1 N) ) ) 
"ARGVAL* 1 

"FORM* (ITIMES N (FACT (SUB1 N) ) ) 
*TAIL* ((ITIMES N (FACT (SUB1 N) ) ) ) 

*ARG1* (((ZEROP N) L) (T (ITIMES N (FACT (SUB1 N) ) ) ) ) 
COND 

"FORM* (COND ( (ZEROP N) L) (T (ITIMES N (FACT (SUB1 N) ) )')•) 
"TAIL* ((COND ((ZEROP N) L) (T (ITIMES N (FACT (SUB1 N) ) ) ) ) ) 

N 1 
FACT 

**TOP«* 



Internal calls to eval , e.g., from cond and the interpreter, are marked on tho 
push-down list by a special mark which the backtrace prints as "FORM*. 5 The 
genealogy of *FORM*'s is thus a history of the computation. Other temporary 
information stored on the stack by the interpreter includes the tail of a 
partially evaluated implicit progn (e.g. a cond clause or lambda expression) 
and the tail of a partially evaluated form (i.e. those arguments not yot 
evaluated), both indicated on the backtrace by "TAIL*, the values of arguments 



Mote that "FORM*, "TAIL*, "ARGVAL* , etc., do not actually appear on the 
backtrace, i.e. evaluating "FORM* or calling stkscan to search for it will 
not work. However, special functions are available for accessing these 
internal blips. 
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that have already been evaluated, indicated by *ARGVAL* , and the names of 
functions waiting to be called, indicated by *FN* . *ARG1*, ... *ARGn* aro used 
by the backtrace to indicate the (unnamed) arguments to subrs. 

Note that a function is not actually entered and does not appear on the stack, 
until its arguments have been evaluated. 5 Also note that the *AR61*, *FORM**, 
*TAIL*, etc. 'bindings 'comprise the actual working storage. In other words, 
in the above example, if a (lower) function changed the value of the *ARGl* 
binding, the cond would continue interpreting the new binding as a list of cond 
clauses. Similarly, if the *ARGVAL* binding were changed, the new value would 
be given to i times as its first argument after its second argument had been 
evaluated, and itimes was actually called. 

The Pushdown List and Compiled Functions 

Calls to compiled functions, and the bindings of their arguments, i.e. names 
and values, are handled in the same way as for interpreted functions (hence the 
compatibility between interpreted and compiled functions). However, compiled 
functions treat free variables in a special way that interpreted functions do 
not. Interpreted functions "look up" free variables when the variable is 
encountered, and may look up the same variable many times. However, compiled 
functions look up each free variable only once. 7 Whenever a compiled function 
is entered, the pushdown list is scanned and the most recent binding for each 
free variable used in the function is found (or if there is no binding, the 
value cell is obtained) and stored on the stack (and marked in a special way to 



except for functions which do not have their arguments evaluated (although 
they themselves may call eval. e.g. cond ) . 



A list of all free variables is generated at compile time, and is in fact 
obtainable from the compiled definition. See Section 18. 
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distinguish this 'binding* from ordinary bindings). Thus, following tho 
bindings of their arguments, compiled functions store on the pushdown list 
pointers to the bindings for each free variable used in the function. 

In addition to the pointers to free variable bindings, compiled functions 
differ from interpreted functions in the way they treat locally bound 
variables, i.e. progs and open lambdas . Whereas in interpreted functions, 
progs and open lambdas are called in the ordinary way as functions, when 
compiled, progs and open lambdas are merged into the functions that contain 
them. However, the variables bound by them are stored on the stack in the 
conventional manner so that functions called from inside them can reference the 
variables freely. 

Pushdown List Functions 

NOTE: Unless otherwise stated, for all pushdown list functions, pos is a 
position on the control stack or a literal atom other than NIL. If pos is an 
atom, (STKPOS pos 1) is used. In this case, if £os is not found, i ,e . , stkpos 
returns NIL, an ILLEGAL STACK ARG error is generated. 

stkpos[ fn ;n ;pos] Searches back the control stack starting at pos 

for the nth occurrence of fn. Returns stack 
position of that fn if found, 5 else NIL. If n is 
NIL, 1 is used. If pos is NIL, the search starts 
at the current position. stkpos[ ] gives the 
current position. 



Currently, a stack position is a pointer to the corresponding slot on tho 
control or parameter stack, i.e. , the address of that cell. It prints as 
an unboxed number, e.g., #32002, and its type is 2 (Section 10). 
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stknth[n ;pos] Value is the stack position of the nth function 

call before position j>os, where n is negative. 9 If 
pos is NIL, the current position is assumed, i .e. , 
stknth[-i] is the call before stknth . Value of 
stknth is NIL, if there is no such call - e.g., 
stknthC-10000]. 

stkname[pos] Value is the name of the function at control stack 

position pos . In this case, pos must be a real 
stack position, not an atom. 

In summary, stkpos converts function names to stack positions, stknth converts 
numbers to stack positions, and stkname converts positions to function names. 

Information about the variables bound at a particular function call, i.e. stack 
position, can be obtained using the following functions: 

stknargs[pos] Value is the number of arguments bound by the 

function at position pos . 

stkargval[n;pos] Value is the nth argument of the function at 

position pos . n=l corresponds to the first 
argument at pos , n=2 to the second, etc. n can 
also be 0 or negative, i.e., stkargval[ 0 ;FOO] is 
the value of the 'binding 1 immediately before the 
first argument to F00, stkargval[ -1 ;F00] the one 
before that, etc. 



In the spaghetti stack system, n positive will mean the nth function call 
before pos searching up the access links, instead of the control links. 
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stkargname[n ;pos] value is the name of the nth argument of the ♦ 

function at position £os. ♦ 



As an example of the use of stknargs and stkargname : 



variables[pos] returns list of variables bound at pos . 



can be defined by: 



(VARIABLES 

[LAMBDA (POS) 
(PROG (N L) 

(SETO N (STKNARGS POS) ) 
LP (COND 

((ZEROP N) 
(RETURN L))) 
(SETQ L (CONS (STKARGNAME N POS) 
D) 

(SETQ N (SUB1 N)) 
(GO LP]) 



The counterpart of variables is also available. 



stkargs[pos] Returns list of values of variables bound at pos . 



The next three functions, stkscan , evalv , and stkeval all involve searching the 
parameter pushdown stack. For all three functions, pos may be a position on 
the control stack, i.e., a value of stkpos or stknth . i0 In this case, the 
search will include the arguments to the function at pos but not any locally 
bound variables, pos may also be a position on the parameter stack, i.e. a 
slot, in which case the search starts with, and includes that position. 
Finally, pos can be NIL, in which case the search starts with the current 
position on the parameter stack. 



or a function name, which is equivalent to stkpos[ pos ; I ] as described 
earlier. 
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stkscan[var ;pos] 



Searches backward on the parameter stack from pos 
for a binding of var. Value is the slot for that 
binding if found, i.e., a parameter stack 
position, otherwise var itself. 



evalv[ var ;pos] 



returris the value of the atom var evaluated as of 
position pos . 



stkeval[ pos ; form] 



is a more general evalv. It is equivalent to 
eval[form] at position pos » i.e., all variables 
evaluated in form , will be evaluated as of pos 



Finally, we have two functions which clear the stacks; 



retf rom[ pos ; value] 



clears the stack back to the function at position 
pos , and effects a return from that function with 
value as its value. 



reteval[ pos ;f orm] 



clears the stack back to the function at position 
pos , then evaluates form and returns with its 
value to the next higher function. In other 
words, reteval[ pos, form] is equivalent to 



retf rom[ pos ; stkeval[ pos ; f orm] ] . 



12 



11 



12 



However, any functions in form that specifically reference the stack, e.g., 
stkpos , stknth, retfrom , etc., 'see* the stack as it currently is. (Seo 
page 12.11-13 for description of how stkeval is implemented.) 

Provided form does not involve any stack functions, as explained in 
footnote 8. 
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We also have: 



mapdl[mapdlfn ;mapdlpos] starts at position mapdlpos (current if NIL), and 

applies mapdlfn , a function of two arguments, to 
the function name at each pushdown position, and 
the pushdown position itself, to stkname[mapdlpos ] 
until the top of stack is reached. Value is NIL. 

For example, mapdl[ ( LAMBDA (X) (AND (EXPRP X) (PRINT X)))] will print all exprs 
on the push-down list. 

mapdl[ ( LAMBDA (X POS) (COND ( ( IGREATERP (STKNARGS POS) 2) (PRINT X] will print 
all functions of more than two arguments. 

searchpdl[srchfn;srchpos] searches the pushdown list starting at position 

srchpos (current if NIL) until it finds a position 
for which srchfn , a function of two arguments, 
applied to the name of the function and the 
position itself is not NIL. Value is 
(name . position) if such a position is found, 
otherwise NIL. 

The Pushdown List and Funarg 

The linear scan up the parameter stack for a variable binding can bo 
interrupted by a special mark called a skip-blip (see Figure 12-1), and a 
pointer to the position on the stack where the search is to be continued. This 
is what is used to make stkeval . page 12.10 work. It is also used by the 
funarg device (Section 11). 

When a funarg is applied, INTERLISP puts a skip-blip on the parameter stack 
with a pointer to the funarg array, and another skip-blip at the top of the 
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funarg array pointing back to the stack. The effect is to make the stack look 
like it has a patch. The names and values stored in the funarg array will thus 
be seen before those higher pn the stack. Similarly, setting a variable whose 
binding is contained in the funarg array will change only the array. Note 
however that as a consequence of this implementation , the same instance oj a 
fu narg object cannot be used recursively . 
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SECTION 13 
NUMBERS AND ARITHMETIC FUNCTIONS 



13.0 General Comments 

There are three different types of numbers in INTERLISP: small integers, large 
integers, and floating point numbers. 1 Since a large integer or floating point 
number can be (in value) any full word quantity (and vice versa), it is 
necessary to distinguish between those full word quantities that represent 
large integers or floating point numbers, and other INTERLISP pointers. We do 
this by "boxing" the number, which is sort of like a special "cons": when a 
large integer or floating point number is created (via an arithmetic operation 
or by read ) , INTERLISP gets a new word from "number storage" and puts the large 
integer or floating point number into that word. INTERLISP then passes around 
the pointer to that word, i.e., the "boxed number", rather than the actual 
quantity itself. Then when a numeric function needs the actual numeric 
quantity, it performs the extra level of addressing to obtain the "value" of 
the number. This latter process is called "unboxing". Note that unboxing does 
not use any storage, but that each boxing operation uses one new word of number 
storage. Thus, if a computation creates many large integers or floating point 
numbers, i.e., does lots of boxes, it may cause a garbage collection of large 



Floating point numbers are created by the read program when a . or an E 
appears in a number, e.g. 1000 is an integer, 1000. a floating point 
number, as are 1E3 and 1.E3. Note that 1000D, 1000F, and 1E3D are perfectly 
legal literal atoms. 
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integer space, GC: 18, or of floating point number space, GC: 16. 



13,1 Integer Arithmetic 
Small Integers 

Small integers are those integers for which smallp is true. In INTERLISP- 10 , 
these are integers whose absolute value is less than 1536. Small integers are 
boxed by offsetting them by a constant so that they overlay an area of 
INTERLISP 1 s address space that does not correspond to any INTERLISP data type. 
Thus boxing small numbers does not use any storage, and furthermore, each small 
number has a unique representation, so that eg may be used to check equality. 
Note that eg should not be used for large integers or floating point numbers, 
e.g., eq[2000 ;addl[ 1999]] is NIL! egj) or equal must be used instead. 

Integer Functions 

All of the functions described below work on integers. Unless specified 
otherwise, if given a floating point number, they first convert the number to 
an integer by truncating the fractional bits, e.g., iplus[2.3;3.8]s5; if given 
a non-numeric argument, they generate an error, NON-NUMERIC ARG. 

It is important to use the integer arithmetic functions, whenever possible, in 
place of the more general arithmetic functions which allow mixed floating point 
and integer arithmetic, e.g., ipius vs plus , igreaterp vs greaterp , because the 
integer functions compile open, and therefore run faster than the general 



Different implementations of INTERLISP-10 may use different boxing 
strategies. Thus, while lots of arithmetic operations mag lead to garbage 
collections, this is not necessarily always the case. 
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arithmetic functions, and because the compiler is "smart" about eliminating 
unnecessary boxing and unboxing. Thus, the expression 

(IPLUS (IQUOTIENT (ITIMES N 100) M) (ITIMES X Y)) will compile to perform only 
one box, the outer one, and the expression 

(IGREATERP (IPLUS X Y) (IDIFFERENCE A B) ) will compile to do no boxing at all. 

Mote that the PDP-10 is a 36 bit machine, so that in INTERL1SP-1Q all integers 
are between -2*35 and 2t35-l.** Adding two integers which produce a result 
outside this range causes overflow, e.g., 2t34 ♦ 2t34. 

The procedure on overflow is to return the largest possible integer, i.e. in 
IMTERLISP-10 2t35 - I. 4 



iplus[Xj ;x 2 ; . . . ;x n 3 Xj ♦ Xg. ♦ . . . ♦ x n 

iminus[x] - x 

id if ference[x;y] x - y 

addl[x] x * 1 

subl[x] x - 1 

itimes[x 1 ;x 2 ; . . . ;x n ] the product of Xj.Xg. . . .xn 



Approximately 34 billion 

If the overflow occurs by trying to create a negative number of too large a 
magnitude, -2t35+i is used instead of 2t35-l. 
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iquotient[x;y] x/y truncated, e.g. , iquotient[3;2]*l, 

iquotient[-3,2]s-l 

iremainder[x;y] the remainder when x is divided by e.g., 

iremainder [3;2]=1 

igreaterp[x;y] T if x > y; NIL otherwise 

ilessp[x;y] T is x < y; NIL otherwise 

zerop[x] defined as eq[x;0]. 

Mote that zerop should not be used for floating point numbers because it uses 
eg . Use eqplxtO] instead, 

minusp[x] T if x is negative; NIL otherwise. Does not 

convert x to an integer, but simply checks sign 
bit. 

eqp[n;m] T if n and m are eg, or equal numbers, NIL 

otherwise, (eg, may be used if n and m are known 
to be small integers.) eqp does not convert n and 
m to integers, e.g., eqp[200Q;2000.3]=NIL, but it 
can be used to compare an integer and a floating 
point number, e.g., eqp[2000;2000.0]sT. eqp does 
not generate an error if n or m are not numbers, 

smallp[n] T if n is a small integer, else NIL, smallp does 

not generate an error if n is not a number. 

fixp[x] x if x is an integer, else NIL. Does not generate 

an error if x is not a number. 
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fix[x] Converts x to an integer by truncating fractional 

bits, e.g., fix[2.3] a 2, fix[-1.7] * -l . if x is 
already an integer, fix[x]*x and doesn't use any 

5 

storage . 

logandCx^ ;x 2 ; . . . ;x n ] lambda no-spread, value is logical and of all its 

arguments, as an integer, e.g., logand[ 7 ;5 ;6>4 . 

logor[x 1 ;x 2 ; . . . ;x n ] lambda no-spread, value is the logical or of all 

its arguments, as an integer, e.g., 
logorC t;3;9]all. 

logxorCx^ ;x 2 ; . . . ;x n ] lambda no-spread, value is the logical exclusive 

or of its arguments, as an integer, e.g., 
logxor[ 11 ;5] s 14, 
logxor[ll;5;9] s logxor[ 14 »,9] s 7. 

lsh[n;m] (arithmetic) left shift, value is n*2tm, i .e . , n is 

shifted left m places. n can be positive or 
negative. If m is negative, n is shifted right -m 
places. 

rsh[n;m] (arithmetic) right shift, value is n*2t-m, i.e., n 

is shifted right m places, n can be positive or 
negative. If m is negative, n is left -m places, 

llsh[n;m] logical left shift. On PDP-10, llsh is equivalent 

to Ish. 



Since FIX is also a lispx command (Section 22), typing FIX directly to 
lispx will not cause the function fix to be called. 
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lrsh[n ;m] 



logical right shift* 



The difference between a logical and arithmetic right shift lies in the 
treatment of the sign bit for negative numbers. For arithmetic right shifting 
of negative numbers, the sign bit is propagated, i.e., the value is a negative 
number. For logical right shift, zeroes are propagated. Note that shifting 
(arithmetic) a negative number 'all the way 1 to the right yields -1, not 0. 

value is the greatest common divisor of x and 
e.g. gcd[72;64>8. 



13.2 Floating Point Arithmetic 

All of the functions described below work on floating point numbers. Unless 
specified otherwise, if given an integer, they first convert the number to a 
floating point number, e.g., fplus[l;2.3] * fplus[ 1 .0 ;2,3] = 3,3; if given a 
non-numeric argument, they generate an error, NON-NUMERIC ARG. 

The largest floating point number (in INTERLISP-10) is 1 .7014118E38, the 
smallest positive (non-zero) floating point number is 1 .4693679E-39 . The 
procedure on overflow is the same as for integer arithmetic. For underflow, 
i.e. trying to create a number of too small a magnitude, the value will be 0, 

fpiusCXj ;x 2 ; .x n ] x i * x 2 4 • • • ♦ x n 

fminus[x] - x 

f timesCXj ;x 2 ; . . . ;x n ]-\ Xj * x 2 * . . . * x n 

fquotient[x;y] x/y 



gcd[x;y] 
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the remainder when x is divided by e.g., 
fremainder[1.0;3.0]a 3.72529E-9. 

T if x is negative; NIL otherwise. Works for both 
integers and floating point numbers. 

T if x and £ are eg, or equal numbers. See 
discussion page 13.4. 

T if x > y, NIL otherwise. 

is x if x is a floating point number; NIL 
otherwise. Does not give an error if x is not a 
number. 

Mote that if numberp[x] is true, then either fixp[x] or floatp[x] is true. 

float[x] Converts x to a floating point number, e.g., 

float[0] s 0.0. 

13.3 Nixed Arithmetic 

The functions in this section are 'contagious floating point arithmetic 1 
functions, i.e., if any of the arguments are floating point numbers, they act 
exactly like floating point functions, and float all arguments, and return, a 
floating point number as their value. Otherwise, they act like the integer 
functions. If given a non-numeric argument, they generate an error, 
NON-NUMERIC ARC. 

plus[ Xj ;x 2 ;x n l x i * x 2 4 • ■• * * x n 



f remainder[x;y] 

minusp[x] 

eqp[x;y] 

fgtp[x;y] 
f loatp[x] 
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minusCx] 



- x 



dif ference[x;y] 
timesCxj ;x 2 ; . . . ;x n J 
quotient[x;y] 



x - y 



x t * x 2 « ... * x n 



if x and £ are both integers, value is 
iquotient[x;y], otherwise fquotient[x;y]. 



remainder[x;y] 



if x and % are both integers* value is 
iremainder[x;y], otherwise f remainder[x;y] . 



greaterp[x;y] 



T if x > y, NIL otherwise. 



lessp[x;y] 



T if x < y, NIL otherwise. 



abs[x] 



x if x > 0, otherwise -x. abs uses greaterp and 
minus , (not lgreaterp and iminus ) . 



13.4 Special Functions 



6 



They utilize a power series expansion and their values are (supposed to be) 27 
bits accurate, e.g., sin[30>.5 exactly. 



expt[m;n] 



value is mtn. If m is an integer and n is a 
positive integer, value is an integer, e.g, 



In IMTERLISP-10, these functions were implemented by J. W. Goodwin by 
"borrowing" the corresponding routines from the FORTRAN library, and hand 
coding them in INTERLISP-10 via ASSEMBLE. 
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sqrt[n ] 



log[x] 



antilog[x] 



sin[x;radiansf lg] 



cos[x;radiansf lg] 
tan[x;radiansf lg] 
arcsin[x;radiansf lg] 



arccos[x;radiansf lg] 



expt[3;4]=81, otherwise the value is a floating 
point number. If m is negative and n fractional, 
an error is generated, 

value is a square root of n as a floating point 
number, n may be fixed or floating point. 
Generates an error if n is negative. sqrt[n] is 
about twice as fast as expt[n;.5] 

value is natural logarithm of x as a floating 
point number, x can be integer or floating point. 

value is floating point number whose logarithm is 
x. x can be integer or floating point, e.g., 
antilogCl] s e = 2.71828... 

x in degrees unless radiansf lg «T . Value is sine of 
x as a floating point number. 

Similar to sin . 

Similar to sin . 

x is a number between -1 and 1 (or an error is 
generated). The value of arcsin is a floating 
point number, and is in degrees unless 
radiansf lg =T. In other words, if 
arcsin[x;radiansf lg]=z then sin[ z ; radians fig ]=x • 
The range of the value of arcsin is -90 to +90 for 
degrees, -n/2 to n/2 for radians. 

Similar to arcsin . Range is 0 to 180, 0 to n. 
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arctan[x;radiansf lg] 



Similar to arcsin. Range is 0 to 180, 0 to n. 



rand[ lower ;upper] Value is a pseudo-random number between lower and 

upper inclusive, i.e. rand can be used to generate 
a sequence of random numbers. If both limits are 
integers, the value of rand is an integer, 
otherwise it is a floating point number. The 
algorithm is completely deterministic, i.e. given 
the same initial state, rand produces the same 
sequence of values. The internal state of rand is 
initialised using the function randset described 
below, and is stored on the free variablo 
randstate. 



randset[x] Value is internal state of rand after randset has 

finished operating, as a dotted pair of two 
integers. If x s NIL, value is current state. If 
x«T, randstate is initialized using the clocks. 
Otherwise, x is interpreted as a previous internal 
state, i.e. a value of randset , and is used to 
reset randstate . For example, 

1 . (SETQ OLDSTATE (RANDSET) ) 

2. Use rand to generate some random numbers. 

3. (RANDSET OLDSTATE) 

4. rand will generate same sequence as in 2. 
13.5 Reusing Boxed Numbers in INTERLISfMO - SETN 

rplaca and rplacd provide a way of cannibalizing list structure for reuse in 
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order to avoid making new structure and causing garbage collections. This 
section describes an analogous function in INTERLISP-10 for large integers and 
floating point numbers, setn. setn is used like setq , i.e., its first argument 
is considered as quoted, its second is evaluated. If the current value of the 
variable being set is a large integer or floating point number, the new value 
is deposited into that word in number storage, i.e., no new storage is used. 
If the current value is not a large integer or floating point number, e.g., it 
can be NIL, setn operates exactly like setq , i.e., the large integer or 
floating point number is boxed, and the variable is set. This eliminates 
initialization of the variable. 

setn will work interpretively, i.e., reuse a word in number storage, but will 
not yield any savings of storage because the boxing of the second argument will 
still take place, when it is evaluated. The elimination of a box is achieved 
only when the call to setn is compiled, since setn compiles open, and does not 
perform the box if the old value of the variable can be reused. 

Caveats concerning use of SETN 

There are three situations to watch out for when using setn . The first occurs 
when the same variable is being used for floating point numbers and largo 
integers. If the current value of the variable is a floating point number, and 
it is reset to a large integer, via setn , the large integer is simply deposited 
into a word in floating point number storage, and hence will be interpreted as 
a floating point number. Thus, 



This technique is frowned upon except in well-defined, localized situations 
where efficiency is paramount. 

The second argument to setn must always be a number or a NON-NUMERIC ARG 
error is generated. 
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-(SETQ FOO 2.3) 
2 .3 

MSETN FOO 10000) 
2.189529E-43 



Similarly, if the current value is a large integer, and the new value is a 
floating point number, equally strange results occur. 



The second situation occurs when a setn variable is reset from a large integer 
to a small integer. In this case, the small integer is simply deposited into 
large integer storage. It will then print correctly, and function 
arithmetically correctly, but it is not a small integer, and hence will not be 
to another integer of the same value, e.g., 



-(SETQ FOO 10000) 
10000 

«-(SETN FOO 1) 
1 

♦-(IPLUS FOO 5) 
6 

-(EQ FOO 1) 
NIL 

-(SMALLP FOO) 
NIL 



In particular, note that zerop will return NIL even if the variable is equal to 
0. Thus a program which begins with FOO set to a large integer and counts it 
down by (SETN FOO (SUB1 FOO)) must terminate with (EQP FOO 0), not (ZEROP FOO). 



Finally, the third situation to watch out for occurs when you want to save the 
current value of a setn variable for later use. For example, if FOO is being 
used by setn , and the user wants to save its current value on FIE, 
(SETO FOO FIE) is not sufficent, since the next setn on FOO will also change 
FIE, because its changes the word in number storage pointed to by FOO, and 
hence pointed to by FIE. The number must be copied, e.g., 
(SETQ FIE (IPLUS FOO)), which sets FIE to a new word in number storage. 



setn[var;x] nlambda function like setq . var is quoted, x is 



13.12 



evaluated, and its value must be a number, var 

will be set to this number. If the current valuo 

of var is a large integer or floating point 

number, that word in number storage is 

cannibalized. The value of setn is the (new) 
value of var. 

13.6 Box and Unbox in INTERLISP-10 

Some applications may require that a user program explicitly perform the boxing 
and unboxing operations that are usually implicit (and invisible) to most 
programs. The functions that perform these operations are loc and va g 
respectively. For example, if a user program executes a TEWEX JSYS using the 
ASSEMBLE directive, the value of the ASSEHBLE expression will have to be boxed 
to be used arithmetically, e.g., (1PLUS X (LOC (ASSEHBLE --))). It must be 
emphasized that 

Arbitrary unboxed numbers should not be passed around as ordinary values 
because they can cause trouble for the garbage collector . 

For example, suppose the value of x were 150000, and you created (VAG X), and 
this just happened to be an address on the free storage list. The next garbage 
collection could be disastrous. For this reason, the function vag must be used 
with extreme caution when its argument's range is not known, 

loc is the inverse of vag . It takes an address, i.e., a 36 bit quantity, and 
treats it as a number and boxes it. For example, loc of an atom, e.g., 
(LOC (QUOTE FOO)), treats the atom as a 36 bit quantity, and makes a number out 
of it. If the address of the atom FOO were 125000, (LOC (QUOTE FOO)) would be 
125000, i.e. the location of FOO. It is for this reason that the box operation 
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is called loc , which is short for location. 

Note that FOO does not print as #364110 (125000 in octal) because the print 
routine recognizes that it is an atom, and therefore prints it in a special 
way, i.e. by printing the individual characters that comprise it. Thus 
(VAG 125000) would print as FOO, and would in fact be FOO. 

loc[x] Makes a number out of x, i.e., returns the 

location of x. 

vag[x] The inverse of loc. x must be a number; the value 

of vag is the unbox of x. 

The compiler eliminates extra vag's and loc 's for example 
(IPLUS X (LOC (ASSEMBLE --))) will not box the value of the ASSEMBLE, and then 
unbox it for the addition. 



vag is an abbreviation of value get. 
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SECTION 14 
INPUT/OUTPUT FUNCTIONS 



14.1 Files 

All input/output functions in 1NTERLISP can specify their source/destination 
file with an optional extra argument which is the name of the file. This file 
must be opened as specified below. If the extra argument is not given (has 
value NIL), the file specified as "primary 88 for input (output) is used, 
Normally these are both T, for terminal input and output. However , the primary 
input/output file may be changed by 

Sets file as the primary input file. Its value is 
the name of the old primary input file. 

input[] returns current primary input file, which 
is not changed* 

output[ file] Same as input except operates on primary output 

file. 

Any file which is made primary must have been previously opened for 
input/output , except for the file f, which is always open. 



The argument name file is used for tutorial purposes only. Subrs do not 
have argument 'names 8 P per se p as described in section 8. 



inputCfile] 1 
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inf ile[file] Opens file for inputs and sets It as the primary 

input file. 2 The value of inf ile is the previous 
primary input file. If file is already open, same 
as input[file]. Generates a FILE WON'T OPEN error 
if file won't open, e.g., file is already open for 
output. 

outf ile[ file] Opens ' file for output, and sets it as the primary 

output file. The value of outfile is the previous 
primary output file,' ' If file is already open, 
same as output[ f ile]. Generates a FILE WON 6 T OPEN 
error if file won't open, e.g., if file is already 
open for input. 

In INTERLISP-10, for all input/output functions, file follows the TENEX 
conventions for file names, i.e. file can be prefixed by a directory name 
enclosed in angle brackets, can contain alt-modes or control-F *s, and can 
include suffixes and/or version numbers. Consistent with TENEX, when a file is 
opened for input and no version number is given, the highest version number is 
used. Similarly, when a file is opened for output and no version number is 
given, a new file is created with a version number one higher than the highest 
one currently in use with that file name. 

In INTERLISP-10, regardless of the file name given to the INTERLISP function 



2 "' 

To open file without changing the primary input file, perform 
input! inf ile[file]J. 

3 

To open file without changing the primary output file, perform 
output[ outf ile[ file]]. 
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that opened the file, INTERLISP maintains only full TENEX file names* in its 
internal table of open files and any function whose value is a file name always 
returns a full file name, e.g. openp[FOO]=FOO. ;3 . Whenever a file argument is 
given to an i/o function P INTERLISP first checks to see if the file is in its 
internal table. If not, INTERLISP executes the appropriate TENEX JSYS to 
"recognize" the file. If TENEX does not successfully recognize the file, a 
FILE NOT FOUND error is generated.^ If TENEX .does recognize the file, it 
returns to INTERLISP the full file name. Then, INTERLISP can continue with the 
indicated operation. If the file is being opened, INTERLISP opens the file and 
stores its (full) name in the file table. If it is being closed, or written to 
or read from, INTERLISP checks - Its , internal table to make sure the file is 
open, and then executes the corresponding operation. 

Note that each time a full file name is not used, 1NTERLISP-10 must call TENEX 
to recognize the name. Thus if repeated operations are to be performed, it is 
considerably more efficient to obtain the full file name once, e.g. via inf ilep 
or outf ilep . Also, note that recognition by TENEX is performed on the user's 
entire directory. Thus, even if only one file is open, say FOO. si, FS 
(F altmode) will not be recognized if the user's directory also contains the 
file FIE.;1. Similarly, it is possible for a file name that was previously 
recognized to become ambiguous. For example, a program performs infile[FOO], 
opening FOO.;l, and reads several expressions from FOO. Then the user types 
control-C, creates a FOO.;2 and reenters his program. Now a call to read 
giving it FOO as its file argument will generate a FILE MOT OPEN error, because 
TENEX will recognize FOO as FOO.;2, 



i.e. name, extension, and version, plus directory name if it differs from 
connected directory. 

except for inf ilep , outf ilep and openp , which in this case return MIL . 
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infilep[file] Returns full file name of file if file is 

recognized as specifying the name of a file that 
can be opened for input, NIL otherwise. In 
JNTERLISP-10, the full file name will contain a 
directory field only if the directory differs from 
the currently attached directory. Recognition is 
in input context, i.e. in INTERLISP-10, if no 
version number is given, the highest version 
number is returned. 

infilep and outfilep do not open any files, or change the primary files t they 
are pure predicates. 

Qutf ilepCf tie] Similar to infilep , except recognition is in 

output context, i.e. in INTERLISP-10, if no 
version number is given, a version number one 
higher than the highest version number is 
returned. 

closef[file] Closes file . Generates an error, FILE NOT OPEN , 

if file not open. If file is NIL, it attempts to 
close the primary input file if other than 
terminal. Failing that, it attempts to close the 
primary output file if other than terminal. 
Failing both, it returns NIL. If it closes any 
file, it returns the name of that file. If it 
closes either of the primary files, it resets that 
primary file to terminal. 

closeallC] Closes all open files (except T), Value is a list 

of the files closed. 
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openp[ file; type] If type sHXL, value is file (full name) if file is 

open either for reading or for writing* Otherwise 
value is NIL . 

If type is INPUT or OUTPUT, value is file if opon 
for corresponding type, otherwise MIL. If type is 
BOTH, value is file if open for both input and 
output, (See iof lie , page 14.6) otherwise MIL. 

Note: the value of openp is NIL if file is not 
recognised, i.e. openp does not generate an error . 

.openpC-3 returns a list of all files open for input 
or output, excluding T. 

Addressable Files 

For most applications, files are read starting at their beginning and 
proceeding sequentially, i.e. the next character read is the one immediately 
following the last character read. Similarly, files are written sequentially. 
A program need not be aware of the fact that there is a file pointer associated 
with each file that points to the location where the next character is to be 
read from or written to, and that this file pointer is automatically advanced 
after each input or output operation. This section describes a function which 
can be used to reposition the file pointer, thereby allowing a program to treat 
a file as a large block of auxiliary storage which, can be access randomly.^ For 



Random access means that any location is as quickly accessible as any 
other. For example, an array is randomly accessible, but a list is not, 
since in order to get to the nth element you have to sequence through the 
first n- 1 elements. 
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example, one application might involve writing an expression at the beginning 
of the file/ and then reading an expression from a specified point in its 
middle. 

A file used in this fashion is much like an array in that it has a certain 
number of addressable locations that characters can be put into or taken from. 
However, unlike arrays, files can be enlarged. For example, if the file 
pointer is positioned at the end of a file and anything is written, the file 
"grows." It is also possible to position the file pointer beyond the end of 
file and then to write. 5 In this case, the file is enlarged, and a "hole" is 
created, which can later be written into. Note that this enlargement only 
takes place at the end of a file; it is not possible to make more room in the 
middle of a file. In other words, if expression A begins at positon 1000, and 
expression B at 1100, and the program attempts to overwrite A with expression 
C, which is 200 characters long, part of B will be clobbered. 



iof ile[f ile] Opens file for both input and output. Value is 

file . Does not change either primary input or 
primary output. If no version number is given, 
default is same as for inf ile , i.e. highest 
version number. 



8 



This particular example requires the file be open for both input and 
output. This can be achieved via the function iof ile described below. 
However, random file input or output can be performed on files that have 
been opened in the usual way by inf ile or outf ile . 

If the program attempts to read beyond the end of file, an END OF FILE 
error occurs . 
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sf ptr[ file ; address] Sets file gointer for file to address. Value is 

old setting. addre$s «- t corresponds to the end of 
file. 10 

If address sNJLp sfptr returns the current value of 
file pointer without changing it. 

f ilepos[x;f ile;start;end;skip;tail]** Searches file for x a la strpos (Section 

10). Search begins at start (or if start =NXL, 
the current position of file pointer), and goes to 
end (or if endaNIL, to the end of f lie ) . Value is 
address of start of matchp or NIL if not found. 
skip can be used to specify a character which 
matches any character in the file. If tail is T, 
and the search is successful the value is the 
address of the first 'character ti/ter the sequence 
of characters corresponding to x, instead of the 
starting address of the sequence. In either case P 



The address of a character (byte) is the number of characters (bytes) that 
precede it in the file, i.e., 0 is the address of the beginning of the 
file. However, the user should be careful about computing the space needed 
for an expression, since end-of-line in INTERtlSP-lO is represented as two 
characters in a file, but nchars only counts it as one. 



Note: in INTERLISP-10 p if a file is opened for output only, either by 
outf ile , or openf[ f ile ; iOOOOOq ] (see page 14.8), TENEX assumes that one 
intends to write a new or different file, even if a version number was 
specified and the corresponding file already exists. Thus, sf ptr[ f ile ; - 1 ] 
will set the file pointer to 0. If a file is opened for both reading and 
writing, either by iof ile or openf [ f ile ;300000q ], TENEX assumes that there 
might be material on the file that the user intends to read. Thus, the 
initial file pointer is the beginning of the file, but sf ptr[ f ile ; - 1 ] will 
set it to the end of the file. Note that one can also open a file for 
appending by openf[file;20000q]. In this case, the file pointer right 
after opening is set to the end of the existing file. Thus, a write will 
automatically add material at the end of the file, and an sfptr is 
unnecessary. 



f ilepos was written by J. W. Goodwin. 
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the file is left so that the next i/o operation 
begins at the address returned as the value of 
f liepos . 



Openf 



The following function is available in INTERLISP-10 for specialized file 
applications : 

openf [ file ;x] opens file , x is a number whose bits specify the 

access and mode for file , i.e. x corresponds to 
the second argument to the TEN EX JSVS OPENF (see 
JSYS Manual), Value is full name of file . 

openf permits opening a file for read, write, execute, or append, etc. and 

allows specification of byte size, i.e. a byte size of 36 enables reading and 

writing of full words, openf does not affect the primary input or output file 

settings, and does not check whether the file is already open - i.e. the same 

IP 

file can be opened more than once, possibly for different purposes. * openp 
will work for files opened with openf . 

The first argument to openf can also be a number, which is then interpreted as 
JFN. This results in a more efficient call to openf , and can be signficant if 
the user is making frequent calls to openf , e.g. switching byte sizes. 



The "thawed 88 bit in x permits opening a file that is already open. 
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JFM Functions in 1WTERLISP-I0 13 



JFM stands for ^ob file number. St is an integral part of the TEWEX file 
system and is described in [Hurl], and in somewhat more detail in the TENEX 
JSYS manual. In IWTERLiSP-10, the following functions are available for direct « 
manipulation of JFNs: B 

opnjfn[f ile] returns the JFN for file . If file not open, 

generates a FILE WOT OPEN error. 

Example: to write a byte on a file 



[ DEFINEQ (BOUT 

(LAMBDA (FILE BYTE) 
(LOC (ASSEMBLE MIL 

(CO (VAG BYTE)) 

(PUSH MP . 1) 

(CQ (VAG (QPNJFN FILE))) 

(POP UP , 2) 

(JSYS 510) 

(MOVE 1,2)3 

or to read a byte from a file 

[ DEFINEQ (BIN 

(LAMBDA (FILE) 

(LOC (ASSEMBLE NIL 

(CO (VAG (OPNJFN FILE))) 
(JSYS 500) 
(MOVE 1 , 2] 

Making BIN and BOUT substitution macros can save boxing and unboxing in 
compiled code. 



13 

The JFN functions were written by J. W. Goodwin. 
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gtjfn[ file ;ext;v;f lags] 



rljfn[ jfn] 



jfns[ jfn;ac3] 



sets up a 'long* call to GTJFN (see JSYS manual). 
file is a file nam© possibly containing control~F 
and/or alt-mode, ext is the default extension, v 
the default version (overriden if file specif ies 
extension/version, e.g. FOO.COM;2). flags is as 
described on page 17, section 2 of JSYS manual. 
file and ext may be strings or atoms; v and flags 
must be numbers. Value is JFN, or NIL on errors. 

releases j£n. rljfn[-i] releases all JFN's which 
do not specify open files. Value of rl jfn is T. 

converts jfn (a small number) to a file name. ac3 
is either MIL, meaning format the file name as 
would openp or other INTERLISP-10 file functions, 
or else is a number, meaning format according to 
JSYS manual. The value of jfns is atomic except 
where enough options are specified by ac3 to 
exceed atom size (> 100 characters). In this 
case, the value is returned as a string. 
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Most of the functions described below have an (optional ) argument Ji le which 
specifies the name of the file on which the operation is to take place, and an 
(optional) argument rdtbl . which specifies the readtable to be used for input. 
If fx I e is MIL. the primary input file will be used. If the file argument is a 
string, input will be taken from that string (and the string pointer reset 
accordingly) . If rdtbl is MIL, the primary readtable will be used, readtables 
are described on page 14.21. 



tVote: in all IMTERLISP-10 symbolic files, end-of-line is indicated by the 
characters carriage-return and . line-feed 'in that order. Accordingly, on input 
from files, LVTERLISP-10 will skip all line-feeds which immediately follow 
carriage-returns. On input from terminal, IMTERLISP will echo a line-feed 
whenever a carriage-return is input. 



For all input functions except readc and peekc . when reading from the terminal. 
control-A erases the last character typed in, echoing a \ and the erased 
character . Control-A will not backup beyond the last carriage return. Typing 
control-Q causes IMTERLISP to print jM and clear the input buffer, i.e. erase 
the entire line back to the last carriage-return . When reading from a file, 
and an end of file is encountered, alt input functions close the file and 
generate an error, EM9 OF FILE.- 



read[f iie srdtbl ;f lg] Reads one S-expression from file* Atoms are 

delimited by the break and separator characters as 
defined in rdtbl . To isiput an atom which contains 
a break or separator characters precede the 
character by the ©scape character %, e.g. AB%(C, 
is the atom AB(C> %% is the atom %> %tA (i;e, 
%eontrol-A) is the atom ?A. For input from the 
terminal, an atom containing an interrupt 
character can be input by typing instead the 
corresponding alphabetic character preceded by 
eontrol-V, e.g. tVC for control-C. 



Mote that the CHARDELETE and LINEOELETE characters can be redefined or 
disabled via setsyntax , see page 14.24. 
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Strings are delimited by double quotes. To input 
a string containing a double quote or a %, precede 
it by % 9 e.g. W AB« W C W is the string AB"C, Note 
that X can always be typed even if next character 
is not 'special', e.g. JCAXBXC is read as ABC. 

If an atom is interprefcable as a number, read will 
create a number, e.g. 1E3 reads as a floating 
point number, 103 as a literal atom, 1.0 as a 
number, 1,0 as a literal atom, etc. Mote that an 
integer can be input in octal by terminating it 
with a 0, e.g. 170 and 15 read in as the same 
integer. The setting of radix , page 14.36, 
determines how integers are printed, i.e. with or 
without Q's. 



When reading fjg>m the terminal , all input is line-buffered to em 
of control-Q.* 0 Thus no characters are actually seen by the p 



lable the action 
program until a 

carriage-return is typed. However, for reading by read , when a matching right 
parenthesis is encountered, the effect is the same as though a carriage return 
were typed, i.e. the characters are transmitted . To indicate this, ItVTERLISP 
also prints a carriage-return line-feed on the terminal. 



fig*! suppresses the carriage-return normally 
typed by read following a matching right 
parenthesis. (However, the characters are still 
given to read - i.e. the user does not have to 
type the carriage return himself.) 



ratom[ f ll«;rdtblj 



Reads in one atom from file. Separation of atoms 



15 



Unless control[T] has been performed (page 14,34). 
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is defined by rdtbl . % is also an escape character 
for ratom , and the remarks concerning eontrol-A, 
control-Q, control-V t and line-buffering also 
apply. 

if the characters comprising the atom would 
normally be interpreted as a number by read , that 
number is also returned by ratom . Note however 
that ratom takes no special action for M whether 
or not it is a break character f i.e. ratom never 
makes a string. 



rstring[ files rdtbl ] 



Reads in one string from file , terminated by next 
break or separator character. Control-A 9 control- 
Q P eontrol-V 9 and % have the same effect as with 
ratom. 



iVote that the break or separator character that terminates a call to ratom or 
rstring is not read by that call, but remains in the buffer to become the first 
character seen by the next reading function that is called* 



ra toms[ a ; f lie ; rdtbl ] 



Calls ratom repeatedly until the atom a is read. 
Returns a list of atoms read, not including a. 



setseprC 1st 5 f Ig 5 rdtbl 3 



Set separator characters for rdtbl . Value is MIL • 



setbrk[ 1st ; fig; rdtbl] 



Set break characters for rdtbl . Value is NIL « 
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For both setsepr and setbrk, 1st is a list of character codes. Tig determines 
the action of setsepr / setbrk as follows: 

NIL clear out indicated readtable and reset break/separator characters to 
be those in 1st . 

0 clear out only those characters in 1st •■ i.e. this provides an 
unsetsepr and unsetbrk . 

1 add characters in 1st. 

Characters specified by setbrk will delimit atoms, and be returned as separate 
atoms themselves by ratom . Characters specified by setsepr will serve only to 
delimit atoms, and are otherwise ignored. For example, if $ was a break 
character and « a separator character, the input stream ABC^^DEFSGH^SS would be 
read by 6 calls to ratom returning respectively ABC, DEF, S, 6H, S, S. 

The elements of 1st may also be characters, e.g. setbrk[(. f ).] has the same 
effect in INTERLISP-10 as setbrkf(46 44)]. Note however that the Characters 1 
1,2,. ..,9 will be interpreted as character codes because they are numbers. 

Note: (, ), [, ], and w are normally break characters, i.e. will be returned as 
separate atoms when read by ratom . If any of these break characters are 
disabled by an appropriate setbrk (or by making it be a separator character), 
its special action for read will not be restored by simply making it be a break 
character again with setbrk. 17 For more details, see discussion in section on 
readtables, page 14.25-26. 



If lst=T, the break/separator characters are reset to be those in the 
system's readtable for terminals, regardless of value of fig, i.e. 
setbrk[T] is equivalent to setbrk[getbrk[T]]. If rdtbl is T, then the 
characters are reset to those in the original system table. 

However, making these characters be break characters when they already are 
will have no effect. 
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Note that the action of % is not affected by setsepr or setbrk . To defeat the 
action of % use escape[], as described below. 

getsepr[rdtbl] Value is a list of separator character codes. 

getbrk[rdtbl] Value is a list of break character codes. 



escape[flg] If f lgsNIL, makes % act like every other character 

for inputJ 8 Normal setting is escape[T]. The 
value of escape is the previous setting. 

ratest[x] If x 2 T, ratest returns T if a separator was 

encountered immediately prior to the last atom 
read by ratom , NIL otherwise. 

If x s NIL, ratest returns T if last atom read by 
ratom or read was a break character, NIL 
otherwise. 



If x « 1, ratest returns T if last atom read 
(by read or ratom ) contained a % (as an escape 
character, e.g., %[ or %A%B%C), NIL otherwise. 

readc[file] Reads the next character including % 9 M , etc, 

i.e. is not affected by break, separator, or 
escape character. Value is the character. Action 
of readc is subject to line-buffering, i.e. readc 



escape does not currently take a readtable argument, but will probably do 
so in the near future. 
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will not return a value until the line has been 
terminated even if a character has been typed. 
Thus, control-A, control-Q, and control-V will 
have their usual effect. If control[T] has been 
executed (page 14.34), defeating line-buffering, 
readc will return a value as soon as a character 
is typed. In addition, if control-A, control»Q, 
or control-V are typed, readc will return them as 
values. 

peekc[f ile;flg] Value is the next character, but does not actually 

read it, i.e. remove it from the buffer. If 
figs MIL, peekc is not subject- to line-buffering, 
i.e. it returns a value as soon as a character has 
been typed. If fljpT, peekc waits until the line 
has been terminated before returning its value. 
This means that control-A, control-Q, and 
control-V will be able to perform their usual 
editing functions. 

lastc[file] Value is last character read from file . 

Mote: read , ratom , ratoms . peekc . readc all wait for input if there is none. 
The only way to test whether or not there is input is to use readp . 

readp[f ile;f lg] Value is T if there is anything in the input 

buffer of file , NIL otherwise. 19 Note that because 



Frequently, the input buffer will contain a single EOL character left over 
from a previous input. For most applications, this situation wants to be 
treated as though the buffer were empty, and so readp returns MIL. However, 
if f lg =T, readp will also return I in this case, i.e. will return T if 
there is any character in the input buffer. 
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of line-buf fering, readp may return T, indicating 
there is input in the buffer, but read may still 
have to wait. 

readline[rdtbl] 20 read s a line from the terminal , returning it as a 

list. If readp[T] is Nil, readline returns NIL. 
Otherwise it reads expressions, using read, 
until it encounters either: 

(1) a carriage-return (typed by the user) that is 
not preceded by any spaces, e.g. 

ABO 

PP 

and readline returns (A B Cr^ 

(2) a list terminating in a •]•„ in which case 
the list is included in the' value of 
readline 9 e.g. A 3 (C O] and readline returns 
(A B (C D) ) . 

(3) an unmatched right parentheses or right 
square bracket, which is not included in the 
value of readline , e.g. 

ABC] 



PO 

Readline actually has two extra arguments for use by the system, but the 
user should consider it as a function of one argument. 



21 



22 



Actually, readline performs (APPLY* LISPXREADFN T), as described in Section 
22. lispxreadfn is initially READ. 

Note that carriage-return, i .e . the EOL character, can be redefined with 
setsyntax , page 14.24. readline actually checks for the EOL character, 
whatever that may be. The same is true for right parenthesis and right 
bracket. 
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and readllne returns (ABC). 



In the case that one or more spaces precede a carriage-return, or a list is 



terminated with a 1 ) 1 » readline will type 



and continue reading on the 



next line, 



e.g. 



A B C ) 
. ..(D~E F) 
.-.(X Y Z] 



and readline returns (A B C (D E F) (X Y Z)). 



skread[ f ile ;rereadstring J 



24 



is a skip read function. 



It moves the file 



pointer for file ahead as if one call to read had 
been performed, without paying the storage and 
compute cost to really read in the structure. 
rereadstring is for the case where the user has 
already performed some readc's and ratom's before 
deciding to skip this expression. In this case, 
rereadstring should be the material already read 
(as a string), and skread operates as though it 
had seen that material first, thus getting its 
paren-count, double-quote count, etc. set up 
properly. 
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If the user then types another carriage return, the line will terminate 
e.g. 

A B C_J> 



and readline returns (A B C) 



24 



skread was written by J. W, Goodwin. It always uses f ilerdtbl for its 
readtable. — — 
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The value of skread is %) if the first thing 
encountered was a closing paren; X] if the read 
terminated on an unbalanced %} 9 i.e. one which 
also would have closed any extant open left 
parens; otherwise the value of skread is NIL. 

14,3 Output Functions 

Host of the Junctions described below have an (optional ) argument file which 
specifies the name of the file on which the operation is to take place. If 
fi I e is NIL, the primary output file will be used. Some of the functions have 
an (optional) argument rdtbl . which specifies the readtable to be used for 
output. If rdtbl is MIL, the primary readtable will be used. 



iVote: in all LVTERLISP-IO symbolic files, end*>of~line is indicated by the 
characters carriage^return and line- feed in that order. Unless otherwise 
stated, carriage-return appearing in the description of an output function 
means carriage-return and line-feed . 

prinl[x;f ile] prints x on file . 

prin2[x;f ilejrdtbl] prints x on file with % J s and ® 8 s inserted where 

required for it to read back in properly by read , 
using rdtbl . 

Both print and prin2 print lists as well as atoms and strings; print is usually 
used only for explicitly printing formatting characters, e.g. 
(PRIffl (QUOTE %[)) might be used to print a left square bracket (the % would 
not be printed by print ) . prin2 is used for printing S-expressions which can 
then be read back into 1NTERLISP with read i.e. break and separator 
characters in atoms will be preceded by X's, e.g. the atom *() 8 is printed as 
%(%) by prin2 . If radix s8, prin2 prints a Q after integers but print does not 
(but both print the integer in octal). 
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print[x;f ile ;rdtbl] Prints the S-expression x using print s followed by 

a carriage-return line-feed. Its vain© is x. 

For all printing functions, pointers other than lists, strings, atoms, or 
numbers, are printed as fN 9 where M is the octal representation of the address 
of the pointer (regardless of radix). Mote that this will not read back in 
correctly , i.e., it will read in as the atom **N* . 

spaces[n ;f ile] Prints n spaces; its value is NIL . 

terpri[file] Prints a carriage-return; its value is NIL . 

Printlevel 

The print functions print , print , and prin2 are all affected by a level 
parameter set hyi 

printlevel[n] Sets print level to n P value is old setting. 

Initial value is 1000. printlevel[ 3 gives current 
setting. 

The variable n controls the number of unpaired left parentheses . which will be 
printed. Below that level, all lists will be printed as &. 

Suppose x s (A (B C (0 (E F) G) H) &). Then if n * 2, print[x] would print 
(A (B C 8? H) K), and if n ■ 3 P (A (B C (D & G) H) K), and if n s 0, just &. 

If printlevel is negative, the action is similar except that a carriage-return 
is inserted between all occurrences of right parenthesis immediately followed 
by a left parenthesis. 

The printlevel setting can be changed dynamically, even while 1NTERLISP is 
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printing, by typing control-P followed by a number, i.e. a string of digits, 
followed by a period or exclamation point. 25 The printlevel will immediately be 
set to this number. 2 * 5 If the print routine is currently deeper than the new 
level, all unfinished lists above that level will be terminated by "--)". 
Thus, if a circular or long list of atoms, is being printed out, typing 
control-PO. will cause the list to be terminated. 



If a period is used to terminate the printlevel setting, the printlevel will be 
returned to its previous setting after this printout. If an exclamation point 
is used, the change is permanent and the printlevel is not restored (until it 
is changed again). 



Mote: printlevel only affects terminal output. Output to all other files acts 
as though level is infinite. 



14.4 Readtables and Terminal Tables 2 ** 

The INTERLISP input and (to a certain extent) output routines are table driven 
by readtables and terminal tables. A readtable is a datum that contains 



25 



26 



27 



28 



As soon as control-P is typed, INTERLISP clears and saves the input buffer, 
clears the output buffer, rings the bell indicating it has seen the 
control-P, and then waits for input which is terminated by any non-number. 
The input buffer is then restored and the program continues. If the input 
was terminated by other than a period or an exclamation point, it is 
ignored and printing will continue, except that characters cleared from the 
output buffer will have been lost. 

Another way of "turning off* 1 output is to type control-p, which simply 
clears the output buffer, thereby effectively skipping the next (up to) 64 
characters. 

Readtables and terminal tables were designed and implemented by D. C. 
Lewis. 

In INTERLISP- 10, readtables are represented (currently) by 128 word arrays. 
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information about the syntax class of each character; e.g. break character, 
separator character, escape character, list or string delimiter, etc. The 
system packages use three readtables: T for input/output from terminals, (the 
value of) f ilerdtbl for input/output from files, and (the value of) editrdtbl , 
for input from terminals while in the editor. These three tables are 
initially equal but not _eg. Using the functions described below, the user may 
change, reset, or copy these tables. He can also create his own readtables, 
and either explicitly pass them to input/output functions as arguments, or 
install them as the primary readtable, via setreadtable , and then not specify a 
rdtbl argument, i.e. use WIL. 

In the discussion below, most functions that accept readtable arguments will 
also accept NIL as indicating the primary readtable, or T as indicating the 
system's readtable for terminals. Where indicated, some will also- accept OR1G 
(not the value of ORIG) as indicating the original system readtable. 

Readtable Functions 

readtablep[ rdtbl] Value is rdtbl , if rdtbl is a real readtable, 

otherwise NIL. 

getreadtableC rdtbl] If rdtbl «NIL, value is primary read table. If 

rdtbl sT, value is system's readtable for 
terminals. If rdtbl is a real readtable, value is 
rdtbl. Otherwise, generates an ILLEGAL READTABLE 
error. 
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setreadtable[rdtbl;f lg] resets primary readtable to be rdtbl . Generates 

ILLEGAL READTABLE error if rdtbl is not nil, T, or 
a real readtable. Value is previous setting of 
primary readtable, i.e. setreadtabl© is suitable 
for use with resetform (section 5). 

copyreadtable[rdtbl] value is a copy of rdtbl. rdtbl can be a real 

readtable, NIL, T, or 0RI6, in which case value is 
a copy of original system readtable, otherwise 
generates an ILLEGAL READTABLE error. Note that' 
copyreadtable is the only function that creates a 
readtable . 



resetreadtable[ rdtbl sfrom] copies (smashes) from into rdtbl ." from and rdtbl 

can be H1L 9 T, or a real readtable. In addition, 
from can be 0R1G P meaning use system 8 s original 
readtable. 

Syntax Classes 

A syntax class is a group of characters which behave the same with respect to a 
particular input/output operation. For example, break characters belong to the 
syntax class BREAK, separators belong to the class SBPR, [ belongs to the class 
LEFTBRACKET , " to STRXNGDEL1H, etc. Characters that are not otherwise special 
belong to the class OTHER. 30 



If f lg =T, setreadtable resets the system readtable for terminals. Note 
that the user can reset the other system readtables with setq , e.g. 
(SETO FILERDTBL (GETREADTABLE) ) . 



There are currently 11 syntax classes for readtables: LEFTBRACKET, 

RI6HTBRACKET, LEFTPAREN, RIGHTPAREN, STRINGDELXH, ESCAPE, BREAK, SEPR, 

BREAKCHAR, SEPRCHAR, and OTHER. Syntax classes for terminal tables are 
discussed on page 14.29. 
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The functions below are used to obtain and (re)set the syntax class of a 
character, ch can either be a character code, or a character* i.e. if ch is a 
number, it is interpreted as a character code. For example, in INTERLISP-10 , 1 
indicates control-A, and 49 indicates the character 1. 

getsyn tax[ ch ; table ] Value is syntax class of ch with respect to table . 

table can be NIL, T, ORIG, or a real readtable or 
terminal table, ch is either a character code, a 
character, or a syntax class. In the last case, 
the value of getsyntax is a list of the character 
codes in that class, e.g. 

getsyntax[BREAK]«getbrk[ ]. 

setsyntax[ch ;class;table] sets syntax class of ch, a character code, or a 

character, table can be either NIL, T, or a real 
readtable or terminal table, class is a syntax 
class, or in the case of read-macro characters 
(page 14.26), an expression of the form 
(type fn). The value of setsyntax is the previous 
class of ch. 

setsyntax will also accept class=NIL, T, ORIG, or 
a real readtable or terminal table, as being 
equivalent to getsyntax[ch ;class], i.e. means give 
ch the syntax class it has in the table indicated 
by class, e.g. setsyntax[%( ;ORIG]. class can also 
be a character code or character, which is 
equivalent to getsyntax[ class; table], i.e. means 
give ch the syntax class of the character 
indicated by class, e.g. setsyntax[ {;%[]. 
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syntaxp[codescla$s;table] table is Nit, T, or a real readtable or terminal 

table. Value is T if code is a member of syntax 
class class , e.g. syntaxp[41 ;LEFTPAREN]^T . 
syntaxp compiles open.. Mote that syntaxp will not 
accept a character as an argument. 

Format Characters 

A format character is a character which is recognized as special by road . 
There are six format characters in 1NTERLISP namely [, 3* ( » h " • and The 
six corresponding syntax classes are; IEFTBRACKET, RI6HTBRACKET, tEFTPAREN , 
RI6BTPAREN , STRXN6DELXM, and ESCAPE « (Note that the class ESCAPE refers to the 
input escape character.) Making a character be a" format character does not 
disable the character currently filling that function'--, i.e. it "is: perfectly 
acceptable to have both { and [ function as left brackets. To disable a format 
character, assign it syntax class OTHER P e.g. set$yntax[% E3 5OTHER]. 

Breaks , Separators,, and Readtables 



The syntax class BREAK (or SEPR) corresponds' • to those characters treated as 
break (or separator) characters by ratom , Thus, getsyntax[ BREAK ;rdtbl} is 
equivalent to getbrk[rdtbl], and setsyntax[ch;BREAK;rdtbl] is equivalent to 
setbrk[ list[ch]; 1 ;rdtblj. Note that the characters corresponding to the syntax 
classes LEFTBRACKET, RXGHTBRACKET, LEFTPAREN, RX6HTPAREN, . STRXN6DELXM, and 
ESCAPE are all break characters, and therefore members of the class BREAK. 
However, getsyntax applied to these characters will return the syntax class 
corresponding to their format character function, not BREAK. 

In fact, getsyntax will never return BREAK or SEPR as a value. Instead, 
characters which are break or separator characters but have no other special 
function belong to the syntax class BREAKCHAR or SEPRCHAR (as well as being 
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members of the class BREAK or SEPR) . In most cases, BREAK can be used 
interchangeably with BREAKCHAR. However , not® that setsyntax[%( sBREAK] is a 
nop (since %( is already a break character), but that setsyntax[%( sBREAKCHAR] 
means make %( be just a break character, and therefore disables the LEFTPAREN 
function of %( . It is equivalent to setsyntax[%( ;0THER] followed by 
setsyntax[%( ; BREAK] . If the user does disable one of the format characters, 
e.g. by performing setsyntax[%( ; OTHER], it is not sufficient for restoring the 
formatting function simply to make the character again into a break character, 
i.e. setsyntax[%( ; BREAK] would not restore %( as LEFTPAREN, 

Read Macro Characters 

The user can define various characters as read macro characters by specifying 
as a class an expression of the form (type fn), where type is MACRO, SPLICE, or 
INFIX, and fn is the name of a function, or a lambda expression. Whenever read 
encounters a read-macro character, it calls the associated function, giving it 
as arguments the input file and readtable being used for that call to read. The 
interpretation of the value returned depends on the type of read-macro: 

(1) MACRO The result is inserted into the input as if that 



expression had been read, 



instead 



of 



the 



read-macro character. For example, 



could be 



defined by: 



[MACRO(LAMBDA(FL RDTBL ) ( KWOTE ( READ FL RDTBL]. 



(2). SPLICE 



The result (which should be a list or NIL) is 



nconc 



•ed into the input list, e.g. if ! is defined 



by (SPLICE (LAMBDA NIL (APPEND FOO))), and the 



value of foo is (A B C), when the user inputs 



(X ! Y), the result will be (X A B C Y) . 
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(3) INFIX 



The associated function is called with the list of 



what has been read (current level list only), in 



tconc format. 



as its third argument. 



The 



function's value is taken as a new tconc list 



which replaces the old one. For example, ♦ could 



be defined by. 



( INFIX ( LAMBDA (FL RDTBL Z) 
(RPLACA (CDR 2) 



(LIST (QUOTE IPLUS) 
( CADR Z) 

(READ FL RDTBL))) 



Z)) 



Note that read-macro characters can be 'nested.' For example, if a is defined 



(SPLICE ( LAMBDA (FL RDTBL) (READ FL RDTBL))), then if the valu© of foo is 
(A B C), and (X =FOO Y) is input, (X (A B C) Y) will be returned. If 
(X !=FOO Y) is input, (X A B C Y) will be returned. 

Note that if a read-macro's function calls read , and the read returns U1L P the 
function cannot distinguish the case where a RX6HTPAREM or RIGHTBRACKET 
followed the read-macro character,, e.g. (A B •■), from the case where the atom 
NIL (or 8 () B ) actually appeared. Thus the first case is disallowed, i.e. 
reading a single RXGHTPAREM or RIGHT8RACKET via a read inside of a read-macro 
function. If this occurs, the paren/bracket will be put back into the input 
buffer, and a READ-MACRO CONTEXT ERROR will be generated. 31 

readmacros[ f lg;rdtbl] If f Ig ^MXL, turns off action of readmacros in 

rdtbl . If flgsT, turns them on. Value is 
previous setting. 



If a call to read from within a readmacro encounters an unmatched 
RIGHTBRACKET within a list, the bracket is also put back into the buffer to 
be read (again) at the higher level. Thus, inputting an expression such as 
(A B '(C D] will work correctly. 



by 



(MACRO (LAMBDA (FL RDTBL) (EVAL (READ f L RDTBL)))) 



and 



by 
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Terminal Tables 



A readtable contains input/output information that is media-independent . For 
example, the action of parentheses is the same regardless of the device from 
which the input is being performed. A terminal table is a datum 0 * 1 that 
contains those syntax classes of characters that pertain to terminal 
input/output operations only, e.g. DELETECHAR (control-A), DELETELINE 
(control-Q), etc. In addition, terminal tables contain such information as how 
line-buffering is to be performed, how control characters are to be 
echoed/printed, whether lower case input is to be converted to upper case, etc* 

Using the functions below, the user may change, reset, or copy terminal tables. 
He can also create his own terminal tables and install them as the primary 
terminal table via settermtable . However, unlike readtables, terminal- tables 
cannot be passed as arguments to input/output functions. 

Terminal Table Functions 

termtablep[ ttbl] value is ttbl, if ttbl is a real terminal table, 

NIL otherwise, 

gettermtable[ ttbl] If ttbl sNIL, value is primary (i.e. current) 

terminal table. If ttbl is a real terminal table, 
value is ttbl . Otherwise, generates an 
ILLEGAL TERMINAL TABLE error, 

settermtable[ ttbl] resets primary terminal table to be ttbl . Value 



In INTERLISP-10, terminal tables are represented (currently) by 16 word 
arrays . 
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is previous ttbl. Generates an 

ILLEGAL TERMINAL TABLE error if ttbl is not a real 
terminal table. 



copytermtable[ ttbl] value is a copy of ttbl « ttbl can be a real 

terminal table, NIL, or ORIG, in which case value 
is a copy of the original system terminal, table. 
Wot© that copytermtable is the only function that 
creates a terminal table. 

resettermtable[ttbl5from] smashes from into ttbl . from and ttbl can be NIL 

or a real terminal table. In addition* from can 
be ORIG, meaning use system's original terminal 
table. 

getsyntax , setsyntax , and syntaxp all work on terminal tables as well as 
readtables. When given NIL as a' table -argument, getsyntax and syntaxp use the 
primary readtable or primary terminal table depending on which table contains 
the indicated class argument, e.g. setsyntax[ch;BREAK] will refer to th© 
primary readtable, setsyntax[ ch ;CHARDELETE] will refer t© the primary terminal 
table. In the absence of such information, all three functions default to the 
primary readtable, e.g. setsyntax[ehl*,eh2] refers to the primary read table. 
If given incompatible class and table arguments, all three functions generate 
errors, e.g. setsyntax[ch; BREAK; ttbl], where ttbl is a terminal table, 
generates an ILLEGAL READTABLE error, getsyntax[CHAROELETE;rdtbl] an ILLEGAL 
TERMINAL TABLE error. 

Terminal Syntax classes 

There are currently six terminal syntax classes: CHARDELETE (or DELETECHAR), 
LINEDELETE (or DELETELINE), RETYPE, CTRLV (or CNTRLV), and EOL These classes 
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correspond (initially) to the characters control-A, control-Q, control-R, 
control-V, and carriagereturn/linef eed All other characters belong to 
terminal syntax class NONE . The classes CHARDELETE, LINEDELETE , RETYPE , CTRLV, 
and EOL can contain at most one character. When a new character is assigned 
one of these syntax classes by setsyntax , the previous character is disabled, 
i.e. reassigned the syntax class NONE, and the value of setsyntax will be the 
code for the previous character of that class, if any, otherwise NIL. 

Terminal Control Functions 

echocontrol[char ;mode;ttbl] Used to indicate how control characters are to be 

echoed or printed, char is a character or 
character code. If mode s IGNORE , char is never 
printed. If mode = REAL, char itself will be 
printed. If mode sSIMULATE , output will be 
simulated. If rnode=UPARROW, char will be printed 
as t followed by the corresponding alphabetic 
Character. The value of echocontrol is the 
previous output mode for char , if mode sNIL, the 
value is the current output mode without changing 
■ it. 

Mote that echoing information can be independently specified for control 
characters only. (However, the function echomode described below can be used 
to disable all echoing.) Therefore, if char is an alphabetic character (or 
code), it refers to the corresponding control character, e.g. 
charcontrolC A;UPARROW] makes control-A echo as tA. All other values of char 
generate ILLEGAL ARG errors. 



On input from a terminal, the EOL character signals to the line buffering 
routine to pass the input back to the calling function. It also is used to 
terminate inputs to readline . page 14.17. 
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echomode[ f Ig ; ttbl] 



If flcpT, turns echoing for terminal table ttbl 
on. If f lgsNIL, turns echoing off. Value is 
previous setting. 



deletecontrol[type;message;ttbl] used for specifying the output protocol 

when a CHARDELETE or LINEDELETE is typed according 
to the following interpretations of type : 



LINEDELETE 

iSTCHDEL 

NTHCHDEL 

POSTCHDEL 

EMPTYCHDEL 

ECHO 
NOECHO 



message is the message printed 
when LINEDELETE character is 
typed. Initially M 4#<cr>" . 

message is the message printed 
the first time CHARDELETE is 
typed. Initially «\ u . 

message is the message printed 
on subsequent CHARDELETE 1 s 
(without intervening 
characters). Initially MM . 

message is the message printed 
when input is resumed following 
a sequence of one or more 
CHARDELETE 's . Initially M \". 

message is the message printed 
when a CHARDELETE is typed and 
there are no characters in the 
buffer. Initially »**<cr>» . 

the characters deleted by 
CHARDELETE are echoed. 

the characters deleted by 
CHARDELETE are not echoed. 



For LINEDELETE, ISTCHDEL, NTHCHDEL, POSTCHDEL, and 
EMPTYCHDEL, the message to be printed must be less 
than 5 characters. The value of deletecontrol will 
be the previous message as a. string. If 



This setting of ISTCHDEL, NTHCHDEL, and POSTCHDEL makes it easy to 
determine exactly what has been deleted, namely all of the characters 
between the Vs. 
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message sNIL, the value will be the previous 
message without changing it. For ECHO and NOECHO, 
the value of deletecontrol is the previous echo 
mode, i.e. ECHO or NOECHO. message is ignored. 

Note: If the user's terminal is a scope terminal, deletecontrol and 
echocontrol can be used to make it really delete the last character by 
performing the following: echocontrol[8;REAL], (8 is code for control-H, which 
is backspace) deletecontrol[NOECHO], (eliminates echoing of deleted characters) 
deletecontrol[lSTCHOEL;"tH *H tt ], and deletecontrol[ NTHCHDEL ; M ?H tH"].- 

raise[f lg;ttbl] If flg=T p input is echoed as typed, but lowercase 

letters are converted to upper case. If f Ig sNIL, 
all characters are passed as typed. Value is 
previous setting. 

Line-buffering and CONTROL 

In INTERLISP *s normal state, characters typed on the terminal (this section 
does not apply in any way to input from a file) are transferred to a line 
buffer. Characters are transmitted from the line buffer to whatever input 
function initiated the request (i.e., read, ratom , rstring , or readc) 36 only 



In INTERLISP-10, both raise[] and raise[T] execute TENEX JSYS calls 
corresponding to the TENEX command NORAISE. Conversion of lowercase 
characters to uppercase before echoing is also available via raise[0], 
which executes the JSYS calls corresponding to the TENEX command RAISE. 
The conversion is then performed at the TENEX level, i.e. before 
INTERLISP-10 even sees the characters. The initial setting of raise in 
INTERLISP-10 is determined by the terminal mode at the time the user first 
starts up the system. Following a sysin , the raise mode is restored to 
whatever it was prior to the corresponding sy stmt . 



peekc is an exception; it returns the character immediately. 
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when a carriage-return is typed. ^ Until this time, the user can delete 
characters one at a time from the input buffer by typing control-A. The 
characters are echoed preceded by a \. Or, the user can delete the entire line 
buffer back to the last carriage-return by typing control~Q, in which case 
INTERLISP echoes ##. 38 (If no characters are in the buffer and either control-A 
or control-Q is typed, INTERLISP echoes ##.) 39 

Mote that this line editing is not performed by read or ratom , but by 
INTERLISP, i.e. it does not matter (nor is it necessarily known) which function 
will ultimately process the characters, only that they are still in the 
INTERLISP input buffer. Note also that it is the function that is currently 
requesting input that determines whether parentheses counting is observed, e.g. 
if the user executes (PROGN (RATOM) (READ) ) and types in A (B C D) he will have 
to type in the carriage-return following the right parenthesis before any 
action is taken, whereas if he types (PR06M (READ) (READ)) h© would, not. 
However, once. a carriage-return has been typed, the entire line is 'available 1 
even if not all of it is processed by the function initiating the request, for 
input, i.e. if any characters are 'left over 8 , they will be returned 
immediately on the next request for input. For example., 
(PROGN ( RATOM ) (READC)) followed by A B carriage-return will perform both 
operations • . 
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As mentioned earlier, for calls from read , the characters are also 
transmitted whenever the parentheses count reaches 0. In this case, if the 
third argument to read is NIL, INTERLISP also outputs a carriage-return 
line -feed. 

Typing rubout clears the entire input buffer at the time it is typed, 
whereas the action of control-A and control-Q occurs at the time they are 
read. Rubout can thus be used to clear type-ahead. 

As described earlier, the CHARDELETE, I I ME DELETE, and EOL characters can 
all be redefined. Therefore, references to control-A, control«Q, or 
carriage return in the discussion actually refer to the current CHARDELETE, 
LINEOELETE, or EOL characters, whatever they may be. 
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Turning-off Line-buffering 



The function control is available to defeat this line-buffering. After 
control[T], characters are returned to the calling function without line- 
buffering as described below. The function that initiates the request for 
input determines how the line is treated: 

1 • read 

if the expression being typed is a list, the effect is the same as though 
control were NIL, i.e. line-buffering until carriage-return or matching 
parentheses. If the expression being typed is not a list, it is returned as 
soon as a break or separator character is encountered, 4 ^ e.g. (READ) followed 
by ABC space will immediately return ABC. Control-A and control-Q editing are 
available on those characters still in the buffer. Thus, if a program is 
performing several reads under control[T], and the user types NOW IS THE TIME 
followed by control-Q, he will delete only TIME since the rest of the line has 
already been transmitted to read and processed. 

2 . r a torn 

characters are returned as soon as a break or separator character is 
encountered. Before then, control-A and control-Q may be used as with read , 
e.g. (RATOM) followed by ABCcontrol*Aspace will return AB, (RATOM) followed by 
(control-A will return ( and type ## indicating that control-A was attempted 
with nothing in the buffer, since the ( is a break character and would 
therefore already have been read. 



An exception to the above occurs when the break or separator character is a 
(» M , or [ , since returning at this point would leave the line buffer in a 
"funny" state. Thus if control is T and (READ) is followed by *ABC( I , the 
A8C will not be read until a carriage-return or matching parentheses is 
encountered. In this case the user could control-Q the entire line, since 
all of the characters are still in the buffer. 
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3* readc / peekc 

the character is returned immediately; no line editing is possible. In 
particular, (READC) followed by control-A will read the eootrol-A, (READC) 
followed by % will read the %• 



control[u;ttbl] u^T eliminates INTERLlSP's normal 

line-buffering for the terminal table ft 
ttbl . * 

us^IL ' restores line-buffering (normal). 



The value of control is its previous setting. 



14.5 Miscellaneous Input/Output Control Functions 

clearbufCf ile;flg] Clears the input buffer for file . If file is T 

and flcj is T, contents of INTERLISP's line buffer 
and the system buffer are saved (and can be 
obtained via linbuf and sysbuf described below). 
When either control-D, eontrol-E* control-H* 
control-P, or control-S is typed, INTERLISP 
automatically does a clearbuf[T;T]. (For control-P 
and control-S 9 INTERLISP restores the buffer after 
the interaction. See Appendix 3.) 

linbufCflg] if flg=T. value is INTERLISP 1 s line buffer (as a 

string) that was saved at last clearbuf[T;T]« If 
f IgsfrjlL, clears this internal buffer. 

sysbuf [fig] same as linbuf for system buffer. 

If both the system buffer and INTERLISP's line buffer are empty, the internal 
buffers associated with linbuf and sysbuf are not changed by a clearbuf [ T $T] . 
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bklinbuf[x] 



x is a string. bklinbuf sets INTERLISP's line 
buffer to x- If greater than 160 characters, 
first 160 taken. 



bk$ysbuf[x] x 1$ a string, bksysbuf sets system buffer to x. 

The effect is the same as though the user typed x. 

bklinbuf , bksysbuf , linbuf . and sysbuf provide a way of 'undoing' a clearbuf . 
Thus if the user wants to "peek" at various characters in the buffer, he could 
perform clearbuf[T;T], examine the buffers via linbuf and sysbuf , and then put 
them back. 

radix[n] Resets output radix 41 to |ri| with sign indicator 

the sign of n. For example, in INTERLISP-10, -9 
will print as shown with the following radices: 

printing 
-9 

68719476727 
i.e. (2136-9) 

-HQ 
777777777767Q 

Value of radix is its last setting. radix[ ] gives 
current setting without changing it. Initial 
setting is 10. 

fltfmtCn] In INTERLISP-10, sets floating format control to n 



Currently, there is no input radix. 



radix 

10 
•10 

8 
-8 
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(See TENEX JSYS manual for interpretation of 'n). 
fltfmt[T] specifies free format (see Section 3). 
Value of f Itfmt is last setting, f ltfmt[ ] returns 
current setting without changing it. Initial 
setting is T, 

linelength[n] Sets the length of the print line for all files. 

Value is the former setting of the line length. 
Whenever printing an atom would go beyond the 
length of the line, a carriage-return is 
automatically inserted first. linelength[ ] 
returns current setting. Initial setting is 72. 

position[ f ile ;n] Gives the column number the next character will be 

read from or printed to, , e.g. after a 
carriage-return, ' gositionsO « If n is non-Nil, * 
resets position to n. * 

Mote that position[file] is not the same as sfptr[file] which gives the 
position in the file, not on the line. 

14.6 Sysin and Sysout 

sysout[file] Saves the user's private memory on file . Also 

saves the stacks* so that if a program performs a 
sysout P the subsequent sysin will continue from 
that point, e.g. 

( PROGN (SYSOUT (QUOTE F00)) (PRINT (QUOTE HELLO))) 
will cause HELLO will be printed after 
(SYSIW (QUOTE FOO)) The value of sysout is file 
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(full name) . A value of NIL indicates the sysout 
was unsuccessful, i.e. , either disk or computer 
error , or user's directory was full. 

Sysout does not save the state of any open files* 

Whenever the INTERLISP system is reassembled and/or reloaded, old sysout files 
are not compatible with the new system. 

sysin[file] restores the state of 1NTERLISP from a sysout 

file; 43 Value is list[file]. If sysin returns 
NIL, there was a problem in reading the file. If 
file is not found, generates a FILE NOT FOUND 
error. 

5 ^ /?ce §M1JJ1 continues immediately where sysout left off. the only way for a 
program to determine whether it is just coming back from a sysin or from a 
sysout is to test the value of sysout . 

For example, (COND ((LISTP (SYSOUT (QUOTE FOO))) (PRINT (QUOTE HELLO)))) will 
cause HELLO to be printed following the sysin , but not when the sysout was 
performed. 



sysout is advised to set the variable sysoutdate to (DATE), i.e. the time 
and date that the sysout was performed. sysout is also advised to 
evaluate the expressions on af tersysoutforms when coming back from a sysin , 
i.e. when the value being returned by sysout is a list. 



In INTERLISP-IO, file is a runnable file, i.e. it is not necessary to start 
up an INTERLISP and call sysin in order to restore the state of the user's 
program. Instead, the user can treat the sysout file the same as a SAV 
file, i.e. use the TENEX RUN command, or simply type the file name to 
TENEX, and the effect will be exactly the same as having performed a sysin . 
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14.7 Symbolic File Input 



readf ile[ f ile] Reads successive S-expressions from file using 

read (with f ilerdtbl as readtable) until the 
single atom STOP is read, or an end of file 
encountered. Value is a list of these 
^-expressions . 

load[f ile ; Idf lg;printf Ig] Reads successive Subexpressions from file (with 

f ilerdtbl as readtable) and evaluates each as it 
is read, until it reads either NIL, or the single 
atom STOP. Value is file (full name). 

If printf lg sT 9 load prints the value of each S- 
expression; otherwise it does not. Idflg affects 
the operation of define , def ineg 9 rpaq , and rpaqq . 
While load is- operating, dfnf Ig (Section 8) is 
reset to Idflg . 44 Thus, if Idflg sMXL, and a 
function is redefined, a message is printed and 
the old definition saved. If Idf lg «T, the old 
definition is simply overwritten. If Idf Ig aPROP, 
the function, definitions are stored on the 
property lists under the property EXPR, If 
Idf Ig sALLPROP, not only function definitions but 
also variables set . by rpaqq and rpaq are stored on 
property lists. 45 



Using resetvar (Section 5). dfnf Ig cannot simply be rebound because it is 
a global variable. See section 18. 



except when the variable has value NOBIND, in which case it is set to the 
indicated value regardless of dfnf Ig . 
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loadfns[ fns;f ile;ldf lg;vars] ® permits selective loading of function 

definitions, fns is a list of function names, a 
single function name, or T, meaning all 
f unctions. 47 file can be either a compiled or 
symbolic file, i.e., any file that can be loaded 
by load . The interpretation of Idf Ig is the samo 
as for load . 

vars specifies which non-DEFINEQ expression are to 
be loaded (i.e. evaluated): T means all, NIL 
means none, VARS is same as (RPAQQ RPAQ) , FNS/VARS 
is same as (fileCOMS fileBLOC&S), and any other 
atom is the same as list[atom]. 

When vars is a list, each atom on vars is compared 
with both car and cadr of non-DEFINEQ expressions, 
e.g. either RPAQQ or FOOCOMS can be used to 
indicate (RPAQQ FOOCOMS --) should be loaded. For 
more complicated specification, each list on vars 
is treated as an edit pattern and matched with the 
entire non-DEFINEQ expression. In other words, a 
non-DEFINEQ expression will be loaded if either 
its car or cadr is ejj to some member of vars , or 
it matches (using edit4e ) some list on vars, e.g. 
( FOOCOMS DECLARE : (DEFLIST & (QUOTE MACRO))) would 



loadfns was originally written by J. W. Goodwin, and subsequently modified 
by W. Teitelman. 



If a compiled definition is loaded, so are all compiler generated 
subf unctions. 
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cause (RPAQO FOOCOHS --). all DECLARE : 's, and all 
DEFLiST's which set up MACRO'S to be read and 
evaluated. 

The value of loadfns Is a list of (the names of) 
the functions that were found, .plus a list of 
those functions not found (if any) headed by the 
atom NOT-FOUND: e.g. (FOO FIE (NOT-FOUND : FUH) ) . 
If vars is non-NIL, the value will also include 
those expressions that were loaded, plus a list of 
those members of vars for which no corresponding 
expressions were found (if any), again headed by 
the atom NOT-FOUND : . 

If f ile sNIL, loadfns will use whereis (page 
14.73) to determine where .the-' first function in 
fns< resides, and load from that file. Mote that 
the file must previously have been "noticed 1 , 
(For more discussion, see page 14.64). . 



loadvars[ vars; file ;ldflg] 



same as loadfns[NIL,f ile;ldf lg;var$3 



1 o.adf rom[ file; f ns ; ldflg ] 



same as loadfns[fns;f ile;ldflg;T] 



As mentioned in section 9 



once the file package knows about the contents of a 



file, the user can edit functions contained in the file without explicitly 



loading them. Similarly, those functions which have not been modified do not 



have to be loaded in order to write out an updated version of the file. Files 



are normally noticed, i.e. their contents become known to the file package 



(page 14.63), when either the symbolic or compiled versions of the file are 



loaded. If the file is wot going to be loaded, the preferred way to notice it 
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is with loadf rotn . For example, if the user wants to ypdate the file F00 by 
editing the function FOOi contained in it, he need only perform loadf rom[ FOOL 
edit[FOOi], and makef ile[FOO], Note that the user can also load some functions 
at the same time by giving loadfrom a second argument, e.g. loadfrom[FOO;F001 ], 
but its raison d'etre is to inform the file package about the existence and 
contents of a particular file. 

loadblock[fn;file;ldflg3 calls loadfns on those functions contained in the 

block declaration containing tn. 4a 

File Maps 

A file map is a data structure which contains a symbolic 'map 1 of the contents 
of a file. Currently, this consists of the begin and end address^ for each 
def ineq expression in the file, the begin and end address for each function 
definition within the def ineq , and the begin and end address for each compiled 
f unction. 60 

makefile , prettydef , loadfns , recompile , and numerous other system functions 
depend heavily on the file map for efficient operation. For example, the file 
map enables loadfns to load selected function definitions simply by setting the 
file pointer to the corresponding address using sfptr , and then performing a 
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49 
50 



loadblock is designed primarily for use with symbolic files, i.e. to load 
the exprs for a given block. It will not load a function which already 
has an in-core expr definition, and it will not load the block name, 
unless it is also one of the block functions. 

byte address, see sfptr . page 14.7. 

The internal representation of the file map is not documented since it may 
change when the map is extended to include information about other than 
just function definitions. 
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single read . Similarly, the file map is heavily used by the 'remake* option of 
prettydef (page 14.68) those function definitions that have been changed since 
the previous version are prettyprinted; the rest are simply copied from the old 
file to the new one, resulting in a considerable speedup. 



6 1 

Whenever a file is read by load or loadfns , a file map is automatically built 4 
and stored on the property list of the root name of the file, under the 
property FILEMAP . Whenever a file is written by prettydef , a file map for the 
new file is also built and stored on the FILEMAP property. 5 ^ In addition, the 
file map is written on the file itself. 5 ^ Thus, in most cases, load and loadf ns 
do not have to build the file map at all, since a file map will usually appear 
in the corresponding file.^ 5 

The procedure followed whenever a system package that uses file maps accesses a 
file is embodied in the function getf ilemap . getf ilemap first checks the 
FILEMAP property to see if a file map for this file was previously obtained or 
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unless buildrnapf lg =NIL . buildmapf Ig is initially T. 

the file name with directory and version number stripped off. 

Building the map in this case essentially comes for free, since it requires 
only reading the current file pointer before and after each definition is 
written or copied. However, building the map does require that prettypr int 
know that it is printing a DEFIMEO expression. For this reason, the user 
should never print a DEFIMEO expression onto a file himself, but should 
instead always use the FNS command, page 14.50. 

For cosmetic reasons, the file map is written as the last expression in the 
file. However, the address of the file map in the file is { over )wr itten 
into the FILECREATED expression that appears at the beginning of the file 
so that the file map can be rapidly accessed without having to scan the 
entire file. 

unless the file was written with buildmapf Ig sNIL, or was created in a pro- 
file map INTERLISP, or outside of INTERliSP altogether. 
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built. 66 If there is none, getf ilemap next checks the first expression on the 
file to see if it is a FXLECREATED expression that also contains the address of 
a FILEMAP. 57 If neither are successful getf ilemap returns NIL, 58 , and a file 
map will be built. 69 



14.8 Symbolic File Output 

writef ile[x;f ile] Writes a date expression onto file, followed by 

successive S-expressions from x, using f ilerdtbl 
as a readtable. If x is atomic, its value is used. 
If file is not open, it is opened. If file is a 
list, car[file] is used and the file is left 
opened. Otherwise, when x is finished, a STOP is 
printed on file and it is closed. Value is file . 
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The full name of the file is also stored on the FILEMAP property along with 
its map. 

currently, file maps for compiled files are not written onto the files 
themselves. However, load and loadfns will build maps for a compiled file 
when it is loaded, and store it on the property FILEMAP. Similary, loadf ns 
will obtain and use the file map for a compiled file, when available. 

getf ilemap also returns NIL, if usemapf lg =NIL, initially T. usemapf lg is 
available primarily to enable the user to recover in those cases where the 
file and its map for some reason do not agree. For example, if the user 
edits a symbolic file that contains a map using a text editor such as TECO, 
inserting or deleting just one character will throw that map off. The 
functions which use file maps contain various integrity checks to enable 
them to detect that something is wrong, and to generate the error FILEMAP 
DOES NOT AGREE WITH CONTENTS OF file-name. In such cases, the user can set 
usenapf lg to NIL, causing the map contained in the file to be ignored, and 
then reexecute the operation, A new map will then be built (unless 
buildmapf lg is also NIL). 

While building the map will not help this operation, it will help in future 
references to this file. For example, if the user performs loadf rom[ FOO] 
where FOO does not contain a file map, the loadfrom will be (slightly) 
slower than if FOO did contain a file map, but subsequent calls to loadfns 
for this version of FOO will be able to use the map that was built as the 
result of the loadfrom , since it will be stored on FOO's FILEMAP property. 
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single read. Similarly, the file map is heavily used by the 'remake' option of 
prettydef (page 14.68) those function definitions that have been changed since 
the previous version are prettyprinted; the rest are simply copied from the old 
file to the new one, resulting in a considerable speedup. 

K 1 

Whenever a file is read by load or loadfns , a file map is automatically built * 
and stored on the property list of the root name 52 of the file, under the 
property FILEWhP . Whenever a file is written by prettydef , a file map for the 
new file is also built and stored on the FILEHAP property. In addition, the 
file map is written on the file itself. 6 *^ Thus, in most cases, load and loadf ns 
do not have to build the file map at all, since a file map will usually appear 
in the corresponding file. 55 

The procedure followed whenever a system package that uses file maps accesses a 
file is embodied in the function getf ilemap . getf ilemap first checks the 
FXLEMAP property to see if a file map for this file was previously obtained or 



61 unless buildmapf lg =NIL. buildmapflg is initially T. 

the file name with directory and version number stripped off, 



Building the map in this case essentially comes for free, since it requires 
only reading the current file pointer before and after each definition is 
written or copied. However, building the map does require that prettypr int 
knovj that it is printing a DEFINEQ expression. For this reason, the user 
should never print a DEFINEQ expression onto a file himself, but should 
instead always use the FNS command, page 14.50. 



For cosmetic reasons, the file map is written as the last expression in tho 
file. However, the address of the file map in the file is (over )written 
into the F JLECREATED expression that appears at the beginning of the file 
so that the file map can be rapidly accessed without having to scan the 
entire file. 



unless the file was written with buildmapf Ig sNIL, or was created in a pro- 
file map IMTERLISP, or outside of INTERIISP altogether. 
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built/ 56 If there is none, getfilemap next checks the first expression on the 
file to see if it is a FILECREATED expression that also contains the address of 
a FILEMAP. 57 If neither are successful getfilemap returns NIL P 6 ^, and a file 
map will be built. 69 



14.8 Symbolic File Output 

writef ile[x;f ile] Writes a date expression onto file , followed by 

successive S-expressions from x, using f ilerdtbl 
as a readtable. If x is atomic, its value is used. 
If file is not open, it is opened. If file is a 
list, car[file] is used and the file is left 
opened. Otherwise, when x is finished, a STOP is 
printed on file and it is closed. Value is file . 



The full name of the file is also stored on the FILEMAP property along with 
its map. 
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currently, file maps for compiled files are not written onto the files 
themselves. However, load and loadfns will build maps for a compiled file 
when it is loaded, and store it on the property FILEMAP. Slmilary, loadfns 
will obtain and use the file map for a compiled file, when available. 

getfilemap also returns NIL, if usemapf Ig sNIL, initially T. usemapf Ig is 
available primarily to enable the user to recover in those cases where the 
file and its map for some reason do not agree. For example, if the user 
edits a symbolic file that contains a map using a text editor such as TECO, 
inserting or deleting just one character will throw that map off. The 
functions which use file maps contain various integrity checks to enable 
them to detect that something is wrong, and to generate the error FILEMAP 
DOES NOT AGREE WITH CONTENTS OF file-name. In such cases, the user can set 
usemapf Ig to NIL, causing the map contained in the file to be ignored, and 
then reexecute the operation. A new map will then be built (unless 
buildmapf Ig is also NIL) . 



While building the map will not help this operation, it will help in future 
references to this file. For example, if the user performs loadf rom[ FOO] 
where FOO does not contain a file map, the loadf rom will be (slightly) 
slower than if FOO did contain a file map, but subsequent calls to loadfns 
for this version of FOO will be able to use the map that was built as the 
result of the loadfrom . since it will be stored on FOO's FILEMAP property. 
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pp[x] nlambda, nospread function that performs 

output[T], setreadtable[T] and then calls 
prettyprint: PP F00 is equivalent to 
PRETTYPRINT( (FOO) ) ; PP(FOO FIE) or (PP FOO FIE) is 
equivalent to PRETTYPRINT( (FOO FIE)). 
Primary output file and primary readtable are 
restored after printing. 

1st is a list of functions (if atomic, its value 
is used). The definitions of the functions are 
printed in a pretty format on the primary output 
file using the primary readtable. For example , 

(FACTORIAL 
[LAMBDA (W) 
(COUO 

((ZEROP N) 
1) 

(T (ITIMES 

Note: prettyprint will operate correctly on functions that are broken , 
broken-in , advised , or have been compiled with their definitions saved on their 
property lists - it prints the original, pristine definition, but does not 
change the current state of the function. If prettyprint is given an atom 
which is not the name of a function,, but has a value 0 it will prettyprint the 



prettyprint[lst] 6<? 61 



N (FACTORIAL (SUB1 N}) 62 



The prettyprint package was written by W. Teitelman. 

prettyprint has a second argument that is T when called from prettydef . In 
this case, whenever prettyprint starts a new function, it prints (on the 
terminal) the name of that function if more than 30 seconds (real time) 
have elapsed since the last time it printed the name of a function. 

In order to save space on files, tabs are used instead of spaces for the 
inital spaces on each line, assuming that each tab corresponds to 8 spaces. 
This results in a reduction of file size by about 30%. Tabs will not be 
used if prettytabflg is set to HIL (initially T) . 
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value." 5 Otherwise,, prettyprint will perform spelling correction. If all 
fails, prettyprint returns (atom NOT PRINTABLE). 



Comment Feature 

A facility for annotating INTERLISP functions is provided in prettyprint . Any 
S-expression beginning with * is interpreted as a comment and printed in the 
right margin. Example: 

( FACTORIAL 

[LAMBDA (N) (* COMPUTES N!) 

( COND 

((ZEROP N) (* 0!«1) 

1) 

(T (« RECURSIVE DEFINITION: 

N!*N*N-1!) 

(ITIMES N (FACTORIAL (SUB1 N]) 

These comments actually form a part of the function definition. Accordingly, a 
is defined as an NLAMBDA NOSPREAD function that returns its argument, i.e. it 
is equivalent to quote . When running an interpreted function, * is entered the 
same as any other INTERLISP function. Therefore, comments should only be 
placed where they will not harm the computation, i.e. where a quoted expression 
could be placed. For example, writing 

(ITIMES N (FACTORIAL (SUB1 N) ) (« RECURSIVE DEFINITION) ) in the above function 
would cause an error when ITIMES attempted to multiply N, N-'ll, and RECURSIVE. 

For compilation purposes, * is defined as a macro which compiles into no 
instructions. Thus, if you compile a function with comments, and load the 
compiled definition into another system, the extra atom and list structures 
storage required by the comments will be eliminated. This is the way the 



except when prettyprint is called from prettydef . 
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comment feature is intended to be used. For more options, see end of this 
section . 

Comments are designed mainly for documenting listings. Thus when 
prettyprinting to the terminal, comments are suppressed and printed as the 
string ^COMMENT*** . 64 

Prettydef 

prettydef[prttyfns;prttyf ilesprttycoms]^ 5 Used to make symbolic files that 

are suitable for loading which contain function 
definitions, variable settings, property lists, et 
al, in a prettyprint format. prettydef uses 
f ilerdtbl as its readtable. The value of 
prettydef is the name of the symbolic file that 
was created. If an error occurs, or a control-D 
is typed, all files that prettydef has opened will 
be closed, and the (partially complete) file being 
written will be deleted. 

The arguments to prettydef are interpreted as follows: 

prttyfns is a list of function names. The functions on the 



The value of ftft comment ftft f Ig determines the action. If aft comment^ ft f Ig is 
NIL, the comment is printed. Otherwise, the value of ^comment^f Ig is 
printed. *»comment aa f Ig is initially set to M ^COMMENT®* ".The function 
PP* is provided to prettyprint functions, including their comments, to the 
terminal. £2l operates exactly like £j> except it first sets ^ a qomment^^f Ig 
; to NIL. ' ' ~ * ~ ~ ~"' 

prettydef actually has three additional arguments for use by the file 
package. See discussion of remaking a file, page 14.69. 
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list are prettyprinteti surrounded by a 
(DEFJNEQ . ..) so that they can be loaded with 
load . If prttyfns is atomic (the preferred 
usage), its top level value is used as the list of 
.function names,, and an rpaqq 6 ® will also be 
written which will set that atom to the list of 
functions when the file is loaded, A print 
expression will also be written which informs the 
user of the named atom or list of functions when 
the file is subsequently loaded, 

prttyfile is the name of the file on which the output is to 

be written. 

The following options exist: 
prttyfile sMIL 

The primary output file is used. 

prttyfile atomic 

The file is opened if not already open, 
and becomes primary output file. File 
is closed at end of prettydef and 
primary output' file is restored. 

prttyfile a list 
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rpaqq and rpaq are like setqq and setq , except they set the top level 
value. See section 5. 

In addition, if any of the functions in the file (including those printed 
by FNS command) are nlambdas, prettydef will print a DECLARE: expression 
suitable for informing the compiler about these functions, in case the user 
recompiles the file without having first loaded the nlambda functions. For 
more discussion, see section 18. 
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Car of the list is assumed to be the 
file name, and is opened if not already 
open. The file is left open at end of 
prettydef . 

prttycoms Is a list of commands interpreted as described 

below. If prttycoms is atomic (the preferred 
usage), its top level value is used and an rpagg 
is written which will set that atom to the list of 
commands when the file is subsequently loaded, 
exactly as with prttyfns . 

These commands are used to save on the output file top level bindings of 
variables, property lists of atoms p miscellaneous INTERL ISP forms to be 
evaluated upon loading, arrays, and advised functions* It also provides for 
evaluation of forms at output time. 

The interpretation of each command in the command list is as follows: 

1. if atomic, an rpagg is written which will restore the top level value of 
this atom when the file is loaded. 

2. (PROP propname atom^ ... atom R ) an appropriate def list will be written 
which will restore the value of propname for each atom^ when the file is 
loaded. 68 If propname is a list, def list 8 s will be written for each 
property on that list. If propname sALL, the values of all user properties 



If atom, does not have the property propname (as opposed to having the 
property with NIL value), a warning message M N0 propname PROPERTY FOR 
atom^ M is printed. The command IF PROP should be used if it is not known 
whether or not an atom will have the corresponding property. 
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(on the property list of each atom^) are saved. 



3. (ARRAY atomj ... atom n ), each atom following ARRAY should have an array as 
its value. An appropriate expression will be written which will set the 
atom to an array of exactly the same sise, type, and contents upon loading. 

4. (P ... ), each S-expression following P will be printed on the output file, 
and consequently evaluated when the file is loaded. 

5. (E ... ), each form following E will be evaluated at output time, i.e., 
when prettydef reaches this command. 



6. (F'NS'fhj ...fn m ), a def ineq is written with the definitions of fnj ... ... m 

exactly as though (fiij ;fn m ) were the first argument to prettydef 



... . f n_ 
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(VARS var^ ... var n ), for each var A , an expression will be written which 
will set its top level value when the file is loaded. If var i is atomic, 
var i will be set to the top-level value it had at the time the file was 
prettydefed, i.e. (RPAQQ var 4 top-level-value) is written/ 1 If var^ is 
non-atomic, it is interpreted as (var form). e.g. 
(FOO (APPEND FIE FUH) ) or (F00 (QUOTE (F001 F002 F003))). In this case the 
expression (RPAQ var form) is written. 
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sysprops is a list of properties used by system functions. Only properties 
not on that list are dumped when the ALL option is used. 

The user should never print a DEFINEQ expression directly onto a file 
himself, but should instead always use the FNS command for dumping 
functions. For more details, see page 14.43. 

HORRIBLEVARS (section 21) provides a way of saving and reloading variables 
whose values contain re-entrant or circular list structure, user data 
types, arrays, or hash arrays. 
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8. (ADVISE fn^ ... fn m ), for each fn n> an appropriate expression will bo 
written which will reinstate the function to its advised state when the 
file is loaded. 

9. (ADVICE fn i ... fn m8 ) , for each fn i0 will writ© a deflist which will put 
the advice back on the property list of the function. The user can then 
use readvise to reactivate the advice. See Section 19. 

10. (BLOCKS blocks .... block^) for each block^ a declare expression will be 
written which the block compile functions interpret as block declarations. 
See Section 18. 

11. (COMS corn^ ... com n h each of the commands com^ ... com^ will be 
interpreted as a prettydef command. 

12. (ADDVARS (var^ . Istj) ... (var^ . lst n )) For each var^, the effect is the 
same as (RPAQ var^ (UNION Istj Var^)), i.e. each element of Ist^ not a 
member of var^ (at load time) is added to it. var^ can initially be 
NOBIND, in which case it is first set to NIL. 

13. (USERHACROS atom^ ... atom )> each atom^ is the name of a user edit macro. 
USERHACROS writes expressions for adding the definitions to usermacros and 
the names to the appropriate spelling lists. (USERHACROS) will save all 
user edit macros . 

14. (IFPROP propname atomj ... atom n ) same as PROP command, except that only 
non-NIL property values are saved. For example, if F001 has property PROP1 
and PROP2, F002 has PROPS , and F003 has property PROP! and PROP3 , 
(IFPROP (PROP! PR0P2 PR0P3) F001 F002 F003) will save only those 5 property 
values. 
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15* (DECLARE: . prettycoms/f lags) Normally expressions written onto a symbolic 
file are (1) evaluated when loaded; (2) copied to the compiled file when 
the symbolic file is compiled (see section 18); and (3) not evaluated at 
compile time. DECLARE: allows the user to override these defaults. The 
output of those prettycoms appearing within the DECLARE: command is 
embedded in a DECLARE: expression, along with any tags that are specified, 
e.g. (DECLARE: EVAL0COMPXLE DONTCOPY (FNS >-) (PROP --.)) would produce 
(DECLARE: EVALGCOMPILE DONTCOPY (DEFINEQ --) (DEFLIST --)). DECLARE: is 
defined as an nlambda nospread function. When declare : is called, it 
processes its arguments by evaluating or not evaluating each list depending 
on the setting of an internal state variable. The tags EVALSLOAD, or 
DOEVAL@LOAD, and DONTEVAL0LOAD can be used to reset this state variable. 
The initial setting is to evaluate. 72 

In each of the commands described above, if the atom * follows the command 
type, the form following the a , i.e., caddr of the command, is evaluated and 
its value used in executing the command, e.g., (FNS « (APPEND FNS1 FNS2) ) / 3 
Mote that (COMS * form) provides a way of computing what should be done by 
prettydef . 

New prettydef commands can be defined via prettydefmacros (see page 14.57). 
If prettydef is given a command not one of the above, and not defined on 



As indicated in section 18, DECLARE: expressions are specially processed by 
the compiler. In this case, the relevant tags are COPY, DOCOPY, DONTCOPY, 
EVALQCOMPILE, DOEVAL0COMPILE , and DONTEVALGCOMPILE . The value of 
declaretagslst is a list of all the tags used in DECLARE: expressions. If a 
tag not on this list appears in a DECLARE: prettycom, prettydef performs 
spelling correcton using declaretagslst as a spelling list. 



Except for the PROP and IFPROP commands, 1n which case the • must follow 
the property name, e.g., (PROP MACRO * FOOMACROS). 
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prefrtydefmacros , it attempts spelling correction '* using prettycomsplst as a 
spelling list. If successful, the corrected version of prettycoms is written 
(again) on the output file. If unsuccessful, prettydef generates an error, 
BAD PRETTYCOM. 

a a a 

Example : 

«-SET( FOOFNS (FOOl F002 F003)) 

-SET(FOOCOMS(FIE (PROP HACRO FOOl F002) (P (MOVD (QUOTE FOOl) 

(QUOTE FIEl] 
♦-PRETTYDEF ( FOOFNS FOO FOOCOHS) 

would create a file FOO containing: 

1. A message which prints the time and date the file was made (done 
automatically) 

2. DEFINEQ followed by the definitions of FOOl, F002, and F003 

3. (PRINT (QUOTE FOOFNS) T) 

4. (RPAQQ FOOFNS (FOOl F003 F003)) 

5. (PRINT (QUOTE FOOVARS) T) 

6. (RPAQQ FOOVARS (FIE ...) 

7. (RPAQQ FIE value of fie) 

8. (DEFLIST (QUOTE ((FOOl propvalue) (F002 propvalue))) (QUOTE MACRO) ) 

9. (MOVD (QUOTE FOOl) (QUOTE FIEl)) 

10. STOP 



unless dwimf Ig sNIL. See Section 17. 

since at this point, the uncorrected prettycoms would already have been 
printed on the output file. When the file is loaded, this will result -in 
prettycoms being reset, and a message printed, e.g. (FOOVARS RESET), The 
value of FOOVARS would then be the corrected version. 
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prettydef functions 



printfns[x] 



x is a list of functions, printfns prints def ineg 
and prettyprints the functions to primary output 
file using primary readtable. Used by prettydef , 
i.e. command (FNS * FOO) is equivalent to command 
(E (PRINTFNS FOO)). 



printdate[ f ile ; changes] 



prints the FILECREATEO expression at beginning of 
prettydefed files that upon loading types the time 
and date the file was made./. - and stores this time 
and date on the property list of file under the 
property FILEDATES. changes is for use by the 
file package. 



tab[ pos ;minspaces;f ile] 



performs appropriate number of spaces to move to 
position pos . minspaces indicates the minimum 
number of spaces to be printed by tab , i.e., it is 
intended to be small number (if NIL, 1 is used). 
Thus, if position * minspaces is greater than pos , 
tab does a terpri and then spaces[pos]. 



endfile[f ile] 



Prints STOP on file and closes it. 



printdef[expr ; left ; def ] 



prints the expression expr in a pretty format on 
the primary output file using the primary 
readtable. left is the left hand margin 
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The message printed when the file is loaded is the value of prettyheader 
followed by the time and date, prettyheader is initially "FILE CREATED . 
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( linelength determines the right hand margin). 2 
is used if left=NlL. 

def sT means expr is a function definition, or a 
piece of one, i.e. prettyprint is essentially 
printdef[getd[fn];NXL;T]. If dej>NIL, no special 
action will be taken for LAMBDA'S, PROG's, CQND's, 
comments, CLISP, etc. def is NIL when prettydef 
calls prettyprint to print variables and property 
lists, and when printdef is called from the editor 
via the command PPV. 



Special Prettyprint Controls 

All variables described below, i.e., #rpars , f irstcol , et al, are global 

variables, see Section 18 <• Therefore, if they are to be changed, they must be 
reset, not rebound. 



#rpars controls the number of right parentheses necessary 

for square bracketing to occur. If #rpars sNIL, no 
brackets are used. #rpars is initialised to 4. 

linelength[n] determines the position of the right margin for 

77 

prettyprint . 

f irstcol is the starting column for comments. Initial 

setting is 48. Comments run between f irstcol and 



Note that makef lie , page 14.66, resets linelength to the value of * 
f ilelinelength . before calling prettydef . f ilelinelength is initially 72. * 



14.55 



linelength . - If a word In a comment ends with a 
' . 5 and is not on the list abbrevlst , and the 
position is greater than halfway between f irstcol 
and linelength, the next word in the comment 
begins on a new line. Also, if a list is 
encountered in a comment, and the position is 
greater than halfway, the list begins on a new 
line, 

prettylcom If a comment is bigger (using count ) than 

prettylcom in size, it is printed starting at 
column 10, instead of f irstcol 7 s prettylcom is 
initialised to 14 (arrived at empirically), 

#carefulcolumns in the interests of efficiency, prettyprint 

approximates the number of characters in each 
atom, rather than calling nchars, when computing 
how much will fit on a line. This procedure works 
satisfactorily in most cases. However, users with 
unusually long atoms in their programs, e.g. such 
as produced by cllspify, may occasionlly encounter 
some glitches in the output produced by 
prettyprint . The value of #carefulcolumns tells 
prettyprint how many columns (counting from the 
right hand margin) in which to actually compute 
nchars instead of approximating. Setting 
#carefulcolumns to 20 or 30 will eliminate the 



Comments are also printed starting at column 10, if their second element is 
also a ft , i.e. comments of the form /(* ® ) : . 
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above glitches, although it will slow down 
prettyprint slightly, flcarefulcolumns is initially 
0. 

widepaper[f Ig] widepaper[T] sets f ilelinelength to 120, f irstcol 

to 80, and prettylcom to 28. This is a useful 
setting for prettyprinting files to be listed on 
wide paper. widepaper[ ] restores these parameters 
to their initial values. The value of widepaper 
is its previous setting. 

commentflg If car of an expression is eg to commentf Ig , the 

expression is treated as a comment, commentflg is 
initialized to ». 

prettyflg If prettyf Ig is Mil, " printdef uses prin2 instead 

of prettyprinting. This is useful for producing a 
fast symbolic dump (see FAST option of makefile , 
page 14.66). Mote that the file loads the same 
as if it were prettyprinted. prettyflg is 
initially set to T. 

clispifyprettyf Ig used to inform prettyprint to CLISPIFY selected 

function definitions before printing them. See 
section 23. 

prettydefmacros Is an assoc-type list for defining substitution 

macros for prettydef . If (FOO (X Y) . corns) 
appears on prettydefmacros , then (FOO A B) 
appearing in the third argument to prettydef will 
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cause A to be substituted for X and 8 for Y 
throughout corns (i.e., cddr of the macro) , and 
then corns treated as a list of commands for 
prettydef J 9 If the atom * follows the name of 
the command, caddr of the command is evaluated 
before substituting in the definition for the 
command. 

prettyprintmacros is an assoc-list that enables the user to format 

selected expressions himself. car of each 
expression being prettyprint ed is looked up on 
prettyprintmacros , and if found, cdr of the 
corresponding entry is applied to the expression. 
If the result of this application is NIL , 
prettyprint will ignore the expression .This gives 
the user the option of printing the expression 
himself in whatever format he pleases. If the 
result is non-NIL, it is prettyprint ed in the 
normal fashion. This gives the user the option of 
computing some other expression to be 
prettyprint ed in its place, prettyprintmacros is 
initially NIL. 

(** E x) A comment of this form causes x to be evaluated at 

prettyprint time, e.g., (** E (RADIX 8)) as a 
comment in a function containing octal numbers can 



The substitution is carried out by subpair (section 6), so that the 
'argument list 8 for the macro can also be atomic. For example, if 
(FOO X . COMS) appears on prettydefmacros . then (FOO A B) will cause (A B) 
to be substituted for X throughout corns . 
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be used to change the radix to produce more 
readable printout. The comment is also printed. 

Converting Comments to Lower Case 

This section is for users operating on terminals without lower case who 
nevertheless would like their comments to be converted to lower case for more 
readable line-printer listings. Users with lower-case terminals can skip to 
the File Package sections (as they can type comments directly in lower case). 

%% If the second atom in a comment is %%> the text of 

the comment is converted to lower case so that it 
looks like English instead of LISP (see next 
page). 

The output on the next page illustrates the result of a lower casing operation. 
Before this function was prettydefed , all comments consisted of upper case 
atoms, e.g., the first comment was (* %% INTERPRETS A SINGLE COMMAND). Note 
that comments are converted only when they are actually written to a file by 
prettydef . 

The algorithm for conversion to lower case is the following: If the first 
character in an atom is J, do not change the atom (but remove the ?). If the 
first character is %, convert the atom to lower case.^ If the atom^ is an 
INTERLXSP word, do not change it. Otherwise, convert the atom to lower case. 

User must type %% as % is the escape character. 

si 

minus any trailing punctuation marks. 

op 

i.e., is a bound or free variable for the function containing the comment, 
or has a top level value, or is a defined function, or has a non-Nil 
property list. 



14.59 



Conversion only affects the upper case alphabet, i.e., atoms already converted 
to lower case are not changed if the comment is converted again. When 
converting, the first character in the comment and the first character 
following each period are left capitalized. After conversion, the comment is 
physically modified to be the lower case text minus the %% flag, so that 
conversion is thus only performed once (unless the user edits the comment 
inserting additional upper case text and another %% flag)* 
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(BREAKCOM 

[ LAMBDA (BRKCOM BRKFL6) 

(PROG (BRKZ) 
TOP (SELECTQ 
BRKCOM 

[t (RETEVAL (QUOTE BREAK 1) 
(QUOTE (ERROR]] 

(GO 



( a Interprets a 
single command.) 



(OK 



(BREAKCOM1 BRKEXP BRKCOM 
(BREAKEXIT)) 



(BREAKCOM1 BRKEXP BRKCOM 
(BREAKEXIT T)) 
(tWGO 



(BREAKCOM1 BRKEXP BRKCOM 
(BREAKEXIT)) 
(RETURN 



(« Evaluate BRKEXP 
unless already evaluated, 
print value, and exit.) 
NIL BRKVALUE ) 

(« Evaluate BRKEXP. 
unless already evaluated, 
do NOT print value, 
and exit. ) 
BRKVALUE BRKVALUE) 

('» Same as GO except 
never saves evaluation 
on history.) 
T BRKVALUE) 



(* User will type 1n expression to be evaluated and 
returned as value of BREAK. Otherwise same as GO.) 



( BREAKCOM i [SETQ BRKZ (CONO 

(BRKCOMS (CAR BRKCOMS ) ) 
(T (LISPXREAO T] 
(QUOTE RETURN) 

NIL NIL (LIST (QUOTE RETURN) 
BRKZ)) 

(BREAKEXIT)) 

( EVAL (« Evaluate BRKEXP but 

do not exit from BREAK.) 

(BREAKCOM1 BRKEXP BRKCOM) 
(COND 

(BRKFLG (BREAK2) 

(PRIN1 BRKFN T) 

(PRIN1 (QUOTE " EVALUATED 

") 

T))) 

(SETQ ! VALUE (CAR BRKVALUE)) 

(* For user's benefit. ) 

) 
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Words on Icaseist will always be converted to 
lower case. Icaseist is initialized to contain 
words which are INTERLISP functions but also 
appear frequently in comments as English words, 
e.g. AND, EVERY, GET, GO, LAST, LENGTH, LIST, etc. 
Thus, in the example on the previous page, not was 
written as *NOT, and GO as tGO in order that they 
might be left in upper case. 

words on ucaselst (that do not appear on Icaseist ) 
will be left in upper case. ucaselst is 
initialised to MIL. 

abbrevlst is used to distinguish between 
abbreviations and words that end in periods. 
Normally, words that end in periods and occur more 
than halfway to the right margin cause carriage 
returns. Furthermore, during conversion to 
lowercase, words ending in periods, except for 
those on abbrevlst , cause the first character in 
the next word to be capitalized. abbrevlst is 
initialised to the upper and lower case forms of 
ETC. I.E. and E.G. 

value is lower case version of x. If fig is T, 
the first letter is capitalized, e.g. 
1-caset FOO;T] ■ Foo, l-case[FOO] « foo. If x is a 
string, the value of 1-case is also a string, e.g. 
l-case[ H FXLE NOT FOUND* ;T] * "File not found". 

Similar to 1-case 
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This section describes a set of functions and conventions for facilitating the 
bookkeeping involved with working in a large system consisting of many symbolic 
files and their compiled counterparts. The file package keeps track of which 
files have been in some way modified and need to be dumped, which files have 
been dumped, but still need to be listed and/or recompiled. The functions 
described below comprise a coherent package for eliminating this burden from 
the user. They require that for each file, the first argument to prettydef be 
NIL and the third argument b© fileCOMS, where file is the name of the file, 
e.g. prettydef [ NIL ;FOO$FOOCOMS]. 64 

All the system functions that perform global file operations, e.g. load , 
loadfns , prettydef , tcompl , recompile , et al, as well as those functions that 
change data stored in files, e.g. editf , editv , DWIM corrections to user 
functions,, reassignment of top-level variables, etc, , interact with the file 
package. Some of these interactions are quite complex, such as those cases 
where the same function appears in several different files, or where the 
symbolic or compiled files reside in other directories, or were originally made 
under a different name, etc. Therefore, this section will not attempt to 
document how the file package works in each and every situation, but instead 
make the deliberately vague statement that it does the * right* thing with 
respect to keeping track of what has been changed, and what file operations 
need to be performed in accordance with those changes. 



The file package was written by W, Teitelman. It can be disabled by 
setting f ilepkgflg to NIL, 



file can contain a suffix and/or version number, e.g. 
PRETTYDEF( NIL F00.TEM;3 FOOVARS) is acceptable. The essential point is 
that the COMS be computable from the name of the file. 



as opposed to 'local' file operations such as those performed by print , 
read , sf ptr . etc. 
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Noticing files 



Operations in the file package can be broken down roughly into three 
categories: (1) noticing files, (2) marking changes, and (3) updating files. 
Files are •noticed' by load and loadfns (or loadf rom, loadvars, etc . ) . All 
file operations in the file package are based on the root name of the file, 
i.e. the filename with version number and/or directory field removed. 
Noticing a file consists of adding its root name to the list filelst, and 
adding the property FILE, value ((fileCOMS . type)), to the property list of 
its root name, 36 83? where type indicates how the file was loaded, e.g. 
completely loaded, only partially loaded as with loadfns , loaded as a compiled 
file, etc. For example, if the user performs load[ <TE I TBLMAN>FOO .ISP ; 2 ] ♦ 
FOO.LSP is added to filelst , and ((FOOCOHS . T)) is put on the property list of 
FOO.LSP. 



The property FILE is used to determine whether or not the corresponding file 
has been modified since the last time it was loaded or dumped as described 
below. In addition, the property FXLECHANGES contains the union of all changes 
since the file was loaded (i.e. there may have been several sequences of 
editing and rewriting the file), and the property FILEDATES a list of version 



The computation of the root name is actually based on the name of the file 
as indicated in the FILECREATED expression appearing at the front of the 
file, since this name corresponds to the name the file was originally made 
under. Similarly, the file package can detect that the file being noticed 
is a compiled file (regardless of its name), by the appearance of more than 
one FILECREATED expressions. In this case, each of the files mentioned in 
the FILECREATED expressions are noticed. For example, if the user performs 
BCOMPL((FOO FIE)), and subsequently loads FOO.COM, both FOO and FIE will be 
noticed . 



The variable loadedf ilelst contains a list of the actual names of the files 
as loaded by load or loadfns . For example, if the user performs 
LOADC<NEWLISP>EDITA.C0H;3], EDITA will be added to filelst , but 
<NEWLISP>EDITA.C0N;3 is added to loadedf ilelst . loadedf ilelst is not used 
by the file package, it is mantained for the user's benefit. 
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numbers and the corresponding file dates. The use and maintenance of these 
properties is explained below. 

Marking changes 



Whenever a function is changed, either explicitly, as with editing, or 
implicitly, e.g. via a DW1FI correction, the function is marked as being changed 
by adding it to the list changedfnslst . A similar procedure is followed for 
variables and changedvarslst . Periodically, the function updatef iles is 
called to find which file(s) contain the functions and variables that have been 

eg 

changed. updatef iles operates by scanning f ilelst and interrogating the 
prettycoms for each file. When (if) such files are found, the name of the 
function or variable is added to the value of the property FILE for the 
corresponding file, and the function or variable removed from changedfnslst or 
changedvarslst . Thus, after updatef iles has completed operating, the files 
that need to be dumped are simply those files on f ilelst for which cdr of their 
FILE property is non-NIL, For example, if the user loads the file FOO 
containing definitions for F001, F002, and F003, edits F002, and then calls 
updatef iles , getp[FOO$F!LE] will be ((F00C0MS . T) F002 ) . Functions or 
variables that remain on their corresponding changedlst are those for which no 
file has been found. 90 
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Initially, the file package only knows about two "types": functions and 
variables, page 14.75 describes how to add additional types. 

updatef iles is called by files ?, cleanup , makefiles , and addf ile , i.e. any 
procedure that requires the FILE property to be up to date. (The user can 
also invoke updatef iles directly.) This procedure is followed rather than 
update the FILE property after each change because scanning f ilelst and 
interrogating each prettycom can be a time-consuming process, and is not 
so noticeable when performed in conjunction with a large operation like 
loading or writing a file. 

e.g., the user defines a new function but forgets to add it to the 
prettycoms for the corresponding file. For this reason, both files ? and 
cleanup print warning messages when changedfnslst is not NIL following an 
updatef iles . 
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Updating Files 

Whenever a file is written using makefile (described below), the 
functions/variables that have been changed, i.e. cdr of the FILE property > are 
moved to the property FILECHANGES, and cdr of the FILE property is reset 
( rplacd ) to NIL. Pi In addition, the file is added to the list notlistedf lies 
and notcompiledf iles . Whenever the user lists a file using listf ties, it is 
removed from notlistedf iles . Similarly, whenever a file is compiled by tcompl, 
recompile , bcompl , or brecompile , the file is removed from notcompiledf iles . 
Thus at each point, the state of all files can be determined. This information 
is available to the user via the function flies? . Similarly, the user can see 
whether and how each particular file has been modified (by examining the 
appropriate property values), dump all files that have been modified, list all 
files that have been dumped but not listed, recompile all files that have been 
dumped but not recompiled, or any combination of any or all of the above by 
using one of the function described below. 

Makefile 

makef ile[f ile;options;reprintfns;sourcef ile] notices file if not 

previously noticed. Performs 

linelength[f ilelinelength], and calls prettydef 
giving it NIL, file, fileCOMS, reprintfns, 
sourcefile, and the list of changes as its 



If the file was not on f ilelst , e.g. the user defined some functions and 
initialized the corresponding prettydoms without loading a file, then the 
file will be •noticed 9 by virtue of its being written, i.e. added to 
f ilelst , and given appropriate FILE, FILEDATES and FILECHANGES properties. 
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arguments, restores original linelength, and 

then adds file to notlistedf iles , 

notcompiledf iles . 9S options is a list of options 

or a single option interpreted as follows: 



FAST perform prettydef with prettyf lg =NIL 

RC call recompile after prettydef or 

brecompile if there are any |U 0C k 
declarations specified in fileCOMS. 

C calls tcompl after prettydef or bcompl 

if there are any block declarations 
specified in fileCOMS. 

CL1SPIFY perform prettydef with 

clispifyprettyf lg sT 9 causing clispif y 
(see Section 23) to be called on each 
function defined as an expr before it is 
prettyprinted. 

WOCLISP performs prettydef with prettytranf lg *T » 
causing CLISP translations to be 



92 



93 



94 



fileCOMS are constructed from the name field only, e.g. makef ile[FOO.TEM] * 

will work. The list of changes is simply cdr of the FILE property, as * 
described earlier, i.e. those items that have been changed since the last 
makef ile . prettydef merges those changes with those handled in previous 

calls to makef ile , and stores the result on the property FILECHANGES, This * 

list of changes is included in the FILECREATED expression printed at the ® 

beginning of the file by printdate , along with the date and version number * 

of the file that was originally noticed, and the date and version number of & 

the current file, i.e. this one. (these two version numbers and dates are ft 

also kept on the property FILEOATE for various integrity checks in * 

connection with remaking a file as described below.) * 

Files that do not contain any function definitions or those that have on 
their property list the property FILETYPE with value DOM'TCOMPILE, are not 
added to notcompiledf iles , nor are they compiled even when options 
specifies C or RC. 

Including any generated via the COHS command or via a prettymaero. 



Alternatively, if file has the property FILETYPE with value CLISP, 
prettydef is called with clisplfyprettyf Ig reset to CHANGES, which will 
cause clispify to be called on all functions marked as having been changed. 
For more details, see discussion of clispifyprettyf Ig in section 23. Mote 
that if file has property FILETYPE with value CLISP, the compiler will 
know to dwimify its functions before compiling them, as described in 
section 18 and 23. 
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LIST 
REMAKE 
NEW 

If F P ST, STF, or S is the next item on options following C or RC, given to tho 
compiler as the answer to the compiler's question LISTING?, e.g. 
makef ile[FOO; (C F LIST) ] will dump FOO, then tcompl or bcompl it specifying 
that functions are not to be redefined, and finally list the file. 

The user can indicate that file must be block compiled together with other 
files as a unit by putting a list of those files on the property list of each 
file under the property FILEGROUP. For example, EDIT and V/EDIT are one such 
group, DWIN, FIX, CUSP, and DWIMIFY another. If file has a FILEGROUP 
property, the compiler will not be called until all files on this property have 
been dumped that need to be. 

Remaking a symbolic file 

Most of the time that a symbolic file is written using prettydef , only some, 
usally a few, of the functions that it contains have been changed since the 
last time the file was written. A considerable savings in time is afforded by 
copying the prettprinted definitions of those functions that have not changed 
from an earlier version of the symbolic file, and prettyprinting only those 



printed, if any, in place of the 
corresponding CLISP expression, e.g. 
iterative statement. 

calls listf iles on file . 

'remakes 1 file. See discussion below. 

does not remake file. 



If makef ilerernakef Ig is I (its initial setting), the default for all calls 
to makefile is to remake. The HEM option is provided in order to override 
this default. 
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functions that have been changed. 



To this end, prettydef has two additional arguments P reprintfns and sourcef lie . 
reprintfns can be a list of functions to be prettyprinted, or EXPRS meaning 
prettyprint all functions with EXPR definitions, or ALL meaning prettyprint all 
functions either defined as exprs or with EXPR properties. sourcef ile is the 
name of the file from which to copy the definitions for those functions that 
are not going to be prettyprinted, i.e. those not specif ied by reprintfns . 
sourcef ile sT means use most recent version (i.e. highest number) of prttyf ile , 
the second argument to prettydef . If sourcef ile cannot be found, prettydef 
prints the message "file NOT FOUND, SO IT WILL BE WRITTEN ANEW" , and proceeds 
as it does when reprintfns and sourcef ile are both NIL. 

Makefile and Remaking a file 

While a file can be remade by appropriately specifying the reprintfns and 
sourcef ile arguments to prettydef , remaking is intended to be used in 
conjunction with makefile , which performs a number of 'do-what-l-mean 1 type of 
services in this context, as described below. When a makefile remake is being 



Remaking a symbolic file does not depend on the earlier version having a 
file map, although it is considerably faster if one does exist. In the 
case of a remake where no file map is available, prettydef scans the file 
looking for the corresponding definition whenever it is about to copy the 
definition to the new file. The scan utilises skread (page 14.18), and 
prettydef does not begin scanning from the beginning of the file each time, 
but instead 'walks through* the original file as it is writing the new 
file. Since the functions are for the most part in the same order, 
prettydef never has to scan very far. However, prettydef also builds a map 
of the functions it has skipped over so that if the order of functions is 
reversed in the new file, prettydef is able to back up and pick up a 
function previously skipped. The net result is still a significant 
savings over (re)prettyprinting the entire file, although not as great a 
savings as occurs when a map is available. 



Mote that doing a remake with reprlntf ns sNIL makes sense if there have 
been changes in the file, but not to any of the functions, e.g. changes to 
vars or property lists. 
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performed," prettydef will be called specifying as reprintfns those functions 
that have been changed since the last version of the file was written. For 
sourcef ile , makef lie obtains the full name of the most recent version of the 
file (that it knows about)^ from the FILEDATES property, and checks to make 
sure that the file still exists, and has the same file date as that stored on 
the FILEDATES property. If it does, makefile calls prettydef specifying that 

i OP 

file as sourcef ile . v * In the case where the most recent version of the file 
cannot be found, makefile will attempt to remake using the original version of 
the file, i.e. the one first loaded, and specifying as reprintfns the union of 
all changes that have been made, which it obtains from the FILECHANGES 
property. if both of these fail, makefile prints the message "CAN'T FIND 
EITHER THE PREVIOUS VERSION OR THE ORIGINAL VERSION OF file, SO IT WILL HAVE TO 
BE WRITTEN ANEW" 9 and then calls prettydef with reprintfns and sourcef ile sNIL. 

When a remake is specified, makefile also checks the state of the file ( cdar of 
the FILE property) to see how the file was originally loaded (page 1.4.64). If 
the file was originally loaded as a compiled file, makefile will automatically 
call loadvars to obtain those DECLARE: expressions that are contained on the 
symbolic file, but not the compiled file, and hence have not been loaded. If 
the file was loaded by loadfns (but not loadfrom ), then loadvars will 



gp 

The normal default for makef ile is to remake, as indicated by the value of 
makef ileremakef Ig , initially T, i.e. the user does not have to explicitly 
include REflAKE as an option. Note that the user can override this default 
for particular files by using the NEW option (page 14.68). 

100 The user can specify reprintfns as the third argument to makefile . 

10 * The user can also specify sourcef ile as the fourth argument to makefile , in 
which case the above checks are not executed. 

102 

This procedure permists the user to load or loadfrom a file in a different 
directory, and still be able to makefile-remake. 
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automatically be called to obtain the non-DEFINEQ expressions . ° If a remake 
is not being performed, i.e. makef ileremakef Ig is NIL, or the option NEW was 
specified, makefile checks the state of the file to make sure that the entire 
symbolic file was actually load ed. If the file was loaded as a compiled file, 
makefile prints the message "CAN'T DUMP: ONLY THE COHPILED FILE HAS BEEN 
LOADED." Similarly, if only some of the symbolics were load via loadfns or 
loadfrom , makefile prints "CAN'T DUMP: ONLY SOME OF ITS SYMBOLICS HAVE BEEN 
LOADED." In both cases, makef ile does not call prettydef » and returns 
(file NOT DUMPED) as its value. 

a a a 



makef iles[ options ;f iles] For each file on files that has been changed, 

performs makef ile[ f ile joptions], If files s NIL, 
f ilelst is used, e.g. makef iles[ LIST] will make 
and list all files. 104 Value is a list of all 
files that are made. 

listf iles[f iles] nlambda, nospread function. Uses bksysbuf to load 

system buffer appropriately to list each file on 
files , (if NIL, notlistedf iles is used) followed 
by a QUIT command, then calls a lower EXEC via 
subsys (section 21). The EXEC will then read from 



If the file has never been loaded or dumped, e.g. the user simply set up 
the fileCOMS himself, then makefile will never attempt to remake the file, 
regardless of the setting of makef ileremakef Ig , or whether the REMAKE 
option was specified, but instead will call prettydef with 
sou reef ile= reprint fns=NIL. 



In this case, if any functions have been defined or changed that are not 
contained in one of the files on f ilelst , a message is printed alerting the 
user. 
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the system buffer, list the files, and QUIT back 
to the program. 



Each file listed is removed from notlistedf iles if 
the listing is completed, e.g. if the user 
control-C's to stop the listing and QUITS. For 
each file not found, listf iles prints the message 
t} <fi1e-name> NOT FOUND" and proceeds to the next 
file on files. 



compilef iles[files] nlambda, nospread function. Executes the RC 

option of makefile for each member of files . (If 
f iles -NIL, notcompiledf iles is used. ) 106 

files?[] Prints on terminal the names of those files that 

have been modified but not dumped, dumped but not 
listed, dumped but not compiled, plus the names of 
those functions (if any) that are not contained in 
any file* 

cleanup[ f iles] nlambda, nospread. Dumps, lists, and recompiles 

(or brecompiles ) any and all files on files 



listf iles calls the function listf ilesl on each file to be listed. 
listfilesl computes the appropriate string to be fed to TEMEX by concatlng 
LISTS, the file name, and the value of listf ilestr . initially ' V . The 
user can reset listf ilestr to specify subcommands for the list command, or 
advise or redef ine listfilesl for more specialized applications. 



If car of files is a list, it is interpreted as the options argmument to 
makef iles . This feature can be used to supply an answer to the compiler's 
LISTING? question, e.g. compilef iles[ (STF) ] will compile each file on 
notcompiledf iles so that the functions are redefined without the exprs 
being saved. 
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requiring the corresponding operation. If 
files 3 NIL, filelst is used. Value is NIL. W 



whereis[x;type;f iles] type is the name of a prettycom. whereis sweeps 

through all the files on files and returns a list 
of all files containing x. whereis knows about and 
expands all prettydef commands and 
prettydefmacros . type sNIL is equivalent to FNS„ 
type s! is equivalent to VARS. Similarly,, f iles ^NIL 
is equivalent to (the value of) filelst , and 
files si is equivalent to 

(APPEND FILELST SYSFILES). 

/Vote that whereis requires that the fileCONS of the corresponding files be 
available . However, in LVTERLISP-10 . the system fileCOHS are clobbered to save 
space. Therefore, if the user wants to ask the location of a system function, 
variable, etc.. he should first load the file <LI$P>FM$/VAR$. 

f ilefnslst[f ile] returns a list of the functions in file , i.e. 

specified by fileCOMS. f ilefnslst knows about 
prettydefmacros . 

newf ile2[name;coms;type] corns is a list of prettydef commands, type is 

usually FNS or VARS but may be BLOCKS, ARRAYS, 
etc. or the name of any other prettydef command. 
If name sNiL, newf ile2 returns a list of all 
elements of type type , ( f ilefnslat and bcompl and 
brecomplle use this option.) 



The user can affect the operation of cleanup by resetting the variable 
cleanupoptions , initially (LIST RC). For example, if cleanupoptions is 
(RC F) f no listing will be performed, and no functions will be redefined as 
the result of compiling. Alternatively, if car of files is a list, it will 
be interpreted as the list of options regardless of the value of 
cleanupoptions . 
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If names! 8 newf lle2 returns T if there are any 
elements of type type , ( makefile uses this option 
to determine whether the file contains any FNS, 
and therefore should be compiled,; and if so, 
whether it contains any BLOCKS, to determine 
whether to call bcompl/brecompile or 
tcompl/ recoropile . ) 

Otherwise, newf ile2 returns T if name is 
"contained" in corns . (whereis uses newf ile2 in 
this way. ) 



® a a 

If the user often employs prettydefmacros , their expansion by the various parts 
of the system that need to interrogate files can result in a large number of 
conses and garbage collections. If the user could inform the file package as 
to what his various prettydefmacros actually produce, this expansion would not 
be necessary. For example, the user may have a macro called GRAMMARS which 
dumps various property list but no functions. Thus, the file package could 
ignore this command when seeking information about FNS. The user can supply 
this information by putting on the property list of the prettymacro, e.g. 
GRAMMARS, under the property PRETTYTYPE, 108 a function (or LAMBDA expression) 
of three arguments, com , type, and name , where com is a prettydef command, and 
type and name corrrespond to the arguments to newf ile2 . The result of applying 
the function to these arguments should be a list of those elements of type type 



If nothing appears on property PRETTYTYPE, the command is expanded as 
before. 
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contained in com. * 



Currently, the file package knows about two "types": functions and variables. 
As described on page 14.65, whenver a function or variable is changed, it is 
added to changedf nslst or ehangedvarslst respectively by newf ile ? (see below). 
Updatef iles operates by mapping down f ilelst and using newf ile2 to determine if 
the corresponding file contains any of the functions on changedfnslst or 
ehangedvarslst . The user can tell the file package about other types by adding 
appropriate entries to prettytypelst . Each element of prettytypelst is a list 
of the form (name-of -changedlist type string), where string is optional. For 
example, prettytypelst is initially ( (CHANGEDFNSLST FNS "functions") 
( CHANGEDVARSLST VkRS)). 110 If the user adds (CHAMGED6RAMLST GRAMMARS ) to 
prettytypelst , then updatef iles will know to move ©laments on changedgramlst to 
the FILE property for the files that contain them. 

The function newf ile ? should be used to mark elements of other types as being 
changed, i.e. to move them to their respective changedlst. 



Actually, when name ^T, it is sufficient to return T if there are any 
elements of type type in com . Similary, when name is an atom other than T 
or NIL, return T if name is contained in com . Finally, if name is a list, 
it is sufficient to return a list of only those elements of type typo 
contained in com that are also contained in name. The user nay take 
advantage of these conventions of newf ile2 to reduce the number of conses 
required for various file package operations, such as calls to whereis that 
edi tf performs when given a function without an expr (see section 9). 
However, note that simply returning a list of all elements of type type 
found in com will always work. 



If string is supplied, f iles? will inform the user if any elements remain 
on the changed list after updatef iles has completed. Similarly, makefiles 
will warn the user that some elements of this type are not going to be 
dumped in the event that it could not find the file to which they belonged. 
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+ newf ile?[name;changedl$t] 



changedlst is the nc?me of a changedlst 9 e.g. 
CHANGEDFWSIST, CHANGEDGRAMLST, etc . newf lie ? 
(undoably) adds name to changedlst . Value is 
name , newf ile ? is used by the editor, DW1M 9 
define, etc . 
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Index for Section 14 



Page 
Numbers 

ABBREVLST (prettydef variable/parameter) 14.56,62 

addressable files 14,5 

ADDVARS (prettydef command) . 14.51 

ADVICE (prettydef command) 14.51 

ADVISE (prettydef command) 14.51 

AFTERSYSOUT FORMS (system variable/parameter) 14.38 

ALL (use in prettydef PROP command) 14.49 

ALLPROP (as argument to load) 14.39 

ARRAY (prettydef command) 14.50 

BAD PRETTYCOM (prettydef error message) 14.53 

BCOMPL 14.67 

bell (typed by system) . 14.21 

BKLINBUF[X] SUBR 14.36 

BKSYSBUF[X] SUBR 14.36,71 

block declarations 14.51 

BLOCKS (prettydef command) 14.51 

break characters ...» 14.13-16,25,34 

BREAK (syntax class) 14.23,25-26 

BREAKCHAR (syntax class) . 14.25 

BRECOMPILE 14.67,72 

BUILDMAPFLG (system variable/parameter) 14.43 

C (makefile option) 14.67 

carriage- re turn . . . 14 . 11-12, 17-20,29,33 

CHANGEDFNSLST (file package variable/parameter) . 14.65,75 

CHANGE DVARSLST (file package variable/parameter).. 14.65,75 

CHARDELETE (syntax class) .... 14.29,31 

CLEANUP[ FILES ] ML" 14.72 

CLEANUPOPTIONS (file package variable/parameter)., 14,73 

CLEARBUF[FILE;FLG] SUBR ... 14.35-36 

CLISPIFY . ... 14.67 

CLISPIFY (makefile option) . 14.67 

CLISPIFYPRETTYFLG (prettydef variable/parameter).. 14.57,67 

CLOSEALL[ ] SUBR 14.4 

CLOSEF[ F ILE ] SUBR 14.4 

CNTRLV (syntax class) . 14.29 

COMMENTFLG (prettydef variable/parameter) 14.57 

comments (in listings) 14.46-47,59-62 

COMPILEFILES[FILES] NL« . 14.72 

COMS (prettydef command) 14.51 

COMTROL[ U ; TTBL ] SUBR 14.12,16,32-35 

control character echoing 14.30 

control-A 14.11,13,16,28-29,31, 

, • . • . 33-35 

control-D 14.35 

control-E . 14.35 

control-F 14.2 

control-H 14.35 

control-0 14.21 

control-P 14.21,35 

control-Q . 14.11-13,16,28-29,31, 

33-34 

control-R 14.29 

control-S 14.35 

control-V 14.11,13,16,29 

COPY (declare: tag) 14.52 

COPYREADTABLE[ RDTBL] SUBR ... 14.23 
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COPYTERMTABLE[ TTBL] SUBR 14.29 

CTRLV (syntax class) 14.29 

DECLARE 14.51 

OECLARETAGSLST (prettydef variable/parameter) ... 14.52 

DECLARE :[ X] ML* 14.52 

DEFLIST[L;PROP] 14.49 

DELETECHAR (syntax class) ... . ........... 14.28-29 

DELETECONTROLC TYPE ;MESSAGE ;TTBL] 14.31 

DELETE LINE (syntax class) 14.28-29 

DFHFLG (system variable/parameter) 14.39 

DOCOPY (declare: tag) 14.52 

DOEVAL(3COHPILE (declare: tag) 14.52 

DOEVAL(?LOAD (declare: tag) 14.52 

DONTCOPY (declare: tag) . . 14.52 

DONTEVAL0COMPXLE (declare: tag) 14.52 

DONTEVAL@LOAD (declare: tag) 14.52 

E (in a floating point number) .. 14.12 

E (prettydef command) 14.50 

E (use in comments) 14.58 

ECHOCONTROL[ CHAR jHODE ;TTBL] . . 14.30 

echoing . . 14 .30 

ECHOMODE[ FLG ; TTBL] SUBR 14.31 

EDITRDTBL ( system var iable/parameter ) 14.22 

END OF FILE (error message) 14.6,11 

ENDFILE[ Y] 14.54 

end- of - line . . . , 14 .7, 11 , 19 

EOL (syntax class) 14.29 

ESCAPE [ FLG ; RDT8L ] SUBR 14.15 

escape character 14.11 

ESCAPE (syntax class) 14.25 

EVAL0COMPILE (declare: tag) 14.52 

EVA L@ LOAD (declare: tag) 14.52 

EXPR (property name) 14.39 

fast symbolic dump 14.57 

FAST (makefile option) 14.67 

FILE CREATED (file package) 14.54 

file maps ., 14.42-44 

file names 14.2-3 

FILE NOT COMPATIBLE (error message) 14.38 

FILE NOT FOUND (error message) 14.3,38 

FILE NOT OPEN (error message) 14.3-4,9 

file package 14.63-75 

file pointer 14.5-7 

FILE WON'T OPEN (error message) 14.2 

FILE ( property name) 14.64,66 

F I LE CHANGES (property name) 14.64,66-67,70 

FILECOMS[ FL;X] 14.63 

FILECREATED . . 14.53-54 

FILEDATES (property name) 14.54,64,67,70 

F ILEFNSLST[ FILE ] . . 14.73 

FILEGROUP (property name) 14.68 

FILELINELENGTH (file package variable/parameter ). . 14.55,57,66 

FILELST (file package variable/parameter) !4.7! p 73,?5 

FILEMAP DOES NOT AGREE WITH CONTENTS OF file-name 

(error message) ... 14.44 

FILEMAP (property name) 14.43 

FILEPKGFLG (file package variable/parameter) .... 14.63 
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FILEPOS[X : FILE;START;EIJ0;SKIP;TAIL] 14.7-8 

FILERDTBL (system variable/parameter) 14.18,39,44,47 

files 14.1-10 

FILES?[] 14.66,72,75 

FILETYPE (property name) 14.67 

FIRSTCOL (prettydef variable/parameter) 14.55,57 

floating point numbers 14.12 

FLTFMT[N] SUBR 14.36-37 

FN5 (prettydef command) 14.50 

FNS/VARS 14.73 

format characters 14.25 

GETBRK[ RDTBL ] SUBR 14.15 

GETFILEMAP[ FILE ;FL] . . 14.43 

GE TREAD TABLE [ RDTBL] SUBR 14.22 

GETSEPR[ RDTBL] SUBR 14.15 

GETSYNTAX[ CH ; TABLE ] 14.24 

GETTERMTABLE[ TTBL] SUBR 14.28 

global variables 14.55 

GTJFN[ FILE ; EXT ;V;FLAGS] 14.10 

IFPROP (prettydef command) 14.51-52 

ILLEGAL ARG (error message) 14.30 

ILLEGAL READTABLE (error message) 14.22-23,29 

ILLEGAL TERMINAL TABLE (error message) 14.28-29 

INFILE[ FILE ] SUBR 14.2,6 

INF ILEP[ FILE ] SUBR 14.3-4 

INFIX (type of read macro) 14.27 

INPUT[FILE] SUBR 14.1 

input buffer j .. 14.16,21,33,35 

input functions 14.11-19 

input/output 14.1-75 

IOFILE[ FILE] SUBR 14.6-7 

OFN 14.8-10 

JFNS[ JFN;AC3] . . 14.10 

JSYS 14.8-10.37 

LASTC[ FILE ] SUBR 14.16 

LCASELST (prettydef variable/parameter) 14.62 

LEFTBRACKET (syntax class) 14.25 

LEFTPAREN (syntax class) 14.25 

LINBUF[ FLG ] SUBR 14.35-36 

line buffer 14.32,35 

LINEDELETE (syntax class) 14.29,31 

LINELENGTHCH] SUBR 14.37,55 

line-buffering 14.12-13.16-17,32-35 

line-feed 14.11,19 

LISPXREADFN (prog. asst. variable/parameter) 14.17 

LIST (makefile option) 14.68 

LISTFILES[ FILES] NL* ...... V 14.66,68,71 

LISTFILESTR (file package variable/parameter) ... 14.72 

LISTFILES1[FILES] 14.72 

literal atoms 14.12 

LOAD[ FILE; LDFLG ; PRINTFLG ] 14.39 

LOADBLOCK[ FN ; FILE ; LDFLG] 14.42 

LOADEDF ILELST (file package variable/parameter) . 14.64 

LOADFNS[ FNS ;FILE ; LDFLG ;VARS] 14.40 

LOADFROM[FILE;FNS: LDFLG] 14.41 

LOADVARS[ VARS ;FILE ; LDFLG] 14.41 

lower case 14.62 
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lower case comments . . 14.59-62 

lower case input 14.32 

L-CASE[X;FLG] . 14.62 

MACRO (type of read macro) 14.26 

MAKEF ILE[ FILE ;OPTIONS ;REPRINTFNS ;SOURCEFILE ] 14.66,68,72 

MAKEF I LE REMAKE FLG 

(file package variable/parameter) 14.68 

MAKEF I LES[ OPT IONS ; FILES] 14.71,75 

margins (for prettyprint) . 14.54 

NCHARS[ X ; FLG ; RDTBL ] SUBR 14.7 

MEW (makefile option) 14.68 

NEWFILE2[ NAME ;COMS; TYPE ;UPDATEFLG] 14.73,75 

NEWF I LE ?[ NAME ; CHANGEDLST ] 14.76 

NO propname PROPERTY FOR atom (error message) ... 14.49 

NOBIND 14.39 

NOCLISP (makefile option) 14.67 

NONE (syntax class) 14.30 

NORAISE (TENEX command) 14.32 

NOT DUMPED (error message) 14.71 

NOT FOUND (error message) 14.72 

NOT FOUND t SO IT WILL BE WRITTEN ANEW 

(error message) 14.69 

(NOT PRINTABLE) .. 14.46 

NOTCOMPI LEDFILES (file package variable/parameter) 14.66-67,72 

NOTLISTEDF ILES (file package variable/parameter).. 14.66-67.71-72 

NOT-FOUND: 14.41 

numbers 14.12-13 

octal 14.12,19 

OPENF[FILE;X] SUBR 14.8 

opening files 14.1 

OP ENP[ FILE ; TYPE ] SUBR 14.3,5,8 

OPNJFN[ F ILE ] SUBR 14.9 

ORIG (used as a readtable) .. 14.22 

OTHER (syntax class) 14.23 

OUTFILE[ FILE ] SUBR 14.2,6-7 

OUTFILEP[ FILE ] SUBR 14.3-4 

OUTPUT[FILE] SUBR 14.1 

output buffer 14.21 

output functions 14.19-21 

P (prettydef command) 14.50 

parentheses counting (by READ) 14.12,33 

PEEKC[ F ILE ] SUBR 14.16,35 

POSITION[FILE] SUBR 14.37 

PP[X] NL« 14.45 

PPV (edit command) 14.55 

PP*[X] \'L* 14.47 

PRETTYCOMSPLST (prettydef variable/parameter) ... 14.53 
PRE TTYDEF[ PRTTYFNS ; PRTTYFILE ; PRTTYCOMS ;REPRINTFNS ; 

SOURCEFILE ;CHANGES] 14.47-55,57,63,66 

prettydef commands 14.49-53 

PRETTYDEFMACROS (prettydef variable/parameter) .. 14.52,57,73-74 

PRETTYFLG (prettydef variable/parameter) 14.57,67 

PRETTYHEADER 14.54 

PRETTYLCOM (prettydef variable/parameter) 14.56-57 

PRETTYPRINT[ FNS ; PRETTYDEFLG] 14.45 

PRETTYPRINTMACROS (prettydef variable/parameter).. 14.58 

PRETTYTABFLG (prettydef variable/parameter) 14.45 
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PRETTYTRANFLG (clisp variable/parameter) 14.67 

PRETTYTYPE (property name) 14.74 

PRETTYTYPELST (file package variable/parameter) . 14.75 

primary input file 14.1-2,4,11 

primary output file 14.1,4,19 

primary readtable 14.11,19,22,29 
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SECTIOM 15 
DEBUGGING - THE BREAK PACKAGE 



15.1 Debugging Facilities 

Debugging a collection of LISP functions involves isolating problems within 
particular functions and/or determining when and where incorrect data are being 
generated and transmitted. In the 1NTERLISP system, there are three facilities 
which allow the user to (temporarily) modify selected function definitions so 
that he can follow the flow of control in his programs, and obtain this 
debugging information. These three facilities together are called the break 
package. All three redefine functions in terms of a system function, break! 
described below. 

Break modifies the definition of its argument, a function fn, so that if a 
break condition (defined by the user) is satisfied, the process is halted 
temporarily on a call to fn. The user can then interrogate the state of the 
machine, perform any computation, and continue or return from the call. 

Trace modifies a definition of a function fn so that whenever fn is called, its 
arguments (or some other values specified by the user) are printed. When the 
value of fn is computed it is printed also. ( trace is a special case of 
break ) . 



The break package was written by W. Teitelman. 
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Breakin allows the user to insert a breakpoint inside an expression defining a 
function. When the breakpoint is reached and if a break condition (defined by 
the user) is satisfied, a temporary halt occurs and the user can again 
investigate the state of the computation. 

The following two examples illustrate these facilities* In the first example, 
the user traces the function factorial . trace redefines factorial so that it 
calls breakl in such a way that it prints some information, in this case the 
arguments and value of factorial , and then goes on with the computation. When 
an error occurs on the fifth recursion, breakl reverts to interactive mode, and 
a full break occurs. The situation is then the same as though the user had 
originally performed BREAK( FACTORIAL) instead of TRACE(FACTORIAL) , and the user 
can evaluate various INTERIISP forms and direct the course of the computation. 
In this case, the user examines the variable n, and instructs breakl to return 
1 as the value of this cell to factorial . The rest of the tracing proceeds 
without incident. The user would then presumably edit factorial to change L to 
1. 

In the second example, the user has constructed a non-recursive definition of 
factorial . He uses breakin to insert a call to breakl Just after the PROG 
label LOOP. This break is to occur only on the last two iterations, i.e., when 
n is less than 2. When the break occurs, the user looks at the value of n . 
mistakenly typing NN. However, the break is maintained and no damage is done. 
After examining n and m the user allows the computation to continue by typing 
OK. A second break occurs after the next iteration, this time with N=0 . When 
this break is released, the function factorial returns its value of 120. 
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-PP FACTORIAL 



(FACTORIAL 
[LAMBDA (N) 
(COND 

((ZEROP N 
L) 

(T (ITIMES N 
FACTORIAL 
"TRACE ( FACTORIAL) 
(FACTORIAL) 
-FACTORIALS) 

FACTORIAL: 
N = 4 

FACTORIAL: 
N = 3 



(FACTORIAL (SUB1 N]) 



FACTORIAL: 
N « 2 

FACTORIAL: 
N = 1 

FACTORIAL: 
N = 0 

U.B.A. 
L 

(FACTORIAL BROKEN) 

:N 

0 

: RETURN 1 

FACTORIAL ■ 1 
FACTORIAL = 1 
FACTORIAL =2 
FACTORIAL = 6 
FACTORIAL = 24 
24 
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«-PP FACTORIAL 

(FACTORIAL 
[ LAMBDA (N) 
(PROG ((Ml)) 
LOOP(COND 

((ZEROP N) 
(RETURN M))) 
(SETO M (ITIMES M N) ) 
(SETQ N (SUB1 N) ) 
(GO LOOP]) 

FACTORIAL 

*-BREAKIN( FACTORIAL (AFTER LOOP) (ILESSP N 2] 

SEARCHING. . . 
FACTORIAL 
-FACTORIALS 5) 

((FACTORIAL) BROKEN) 
: NN 

U.B.A. 

NN 

(FACTORIAL BROKEN AFTER LOOP) 

:N 

:M 

120 

:OK 

(FACTORIAL) 

((FACTORIAL) BROKEN) 

:N 

0 

:OK 

(FACTORIAL) 
120 



15.2 Breakl 



The basic function of the break package is breakl . Whenever 1NTERL1SP types a 
message of the form (- BROKEN) followed by ':' the user is then 'talking to' 
breakl , and we say he is 'in a break.' breakl allows the user to interrogate 
the state of the world and affect the course of the computation. It uses the 
prompt character ':' to indicate it is ready to accept input(s) for evaluation, 
in the same way as evalqt uses '*-' . The user may type in an expression for 
evaluation as with evalqt , and the value will be printed out, followed by 
another :. Or the user can type in one of the commands specifically recognized 
by breakl described below. 
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Since break! puts all of the power of 1NTERLISP at the user's command, he can 
do anything he can do at evalqt . For example, he can insert new breaks on 
subordinate functions simply by typing: 

(BREAK fnl fn2 . ..) 

or he can remove old breaks and traces if too much information is being 
supplied: 

(UNBREAK fn3 fn4 ...) 
He can edit functions, including the one currently broken: 
EDITF(fn) 

For example, the user might evaluate an expression, see that the value was 
incorrect, call the editor, change the function, and evaluate the expression 
again, all without leaving the break. 

Similarly, the user can prettyprint functions, define new functions or redefine 
old ones, load a file, compile functions, time a computation, etc. In short, 
anything that he can do at the top level can be done while inside of the break. 
In addition the user can examine the pushdown list, via the functions described 
in Section 12, and even force a return back to some higher function via the 
function retf rom or reteval . 

It is important to emphasize that once a break occurs, the user is in complete 
control of the flow of the computation, and the computation will not proceed 
without specific instruction from him. If the user types in an expression 
whose evaluation causes an error p the break is maintained. Similarly if the 
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user aborts a computation^ initiated from within the break, the break is 
maintained. Only if the user gives one of the commands that exits from the 
break, or evaluates a form which does a retf rom or reteval back out of break! , 
will the computation continue. 

Mote that breakl is just another INTERLISP function, not a special system 
feature like the interpreter or the garbage collector. It has arguments which 
are explained later, and returns a value, the same as cons or cond or prog or 
any other function* The value returned by breakl is called 'the value of the 
break.' The user can specify this value explicitly by using the RETURN command 
described below. But in most cases, the value of a is given implicitly, via a 
GO or OK command, and is the result of evaluating 'the break expression,' 
brkexp , which is one of the arguments to breakl . 

The break expression is an expression equivalent to the computation that would 
have taken place had no break occurred. For example, if the user breaks on the 
function FOO, the break expression is the body of the definition of FOO. When 
the user types OK or GO, the body of FOO is evaluated, and its value returned 
as the value of the break, i.e. to whatever function called FOO. The effect is 
the same as though no break had occurred. In other words, one can think of 
breakl as a fancy eval , which permits interaction before and after ©valuation. 
The break expression then corresponds to the argument to eval. 



By typing control-E, see Section 16. 

Except that breakl does not 'turn off control-D, i.e. a control-D will 
force an immediate return back to the top level. 
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Break Commands 



GO 



Releases the break and allows the computation to 
proceed. breakl evaluates brkexp , its first 
argument, prints the value of the break. brkexp 
is set up by the function that created the call to 
breakl . For break or trace , brkexp is equivalent 
to the body of the definition of the broken 
function. For breakin , using BEFORE or AFTER, 
brkexp is NIL. For breakin AROUND, brkexp is the 
indicated expression. See breakin , page 15.21. 



OK 



Same as GO except the value of brkexp is not 
printed. 



EVAL 



Same as GO or OK except that the break is 
maintained after the evaluation. The user can 
then interrogate the value of the break which is 
bound on the variable lvalue , and continue with 
the break. Typing GO or OK following EVAL will 
not cause reevpluation but another EVAL will. 
EVAL is a useful command when the user is not sure 
whether or not the break will produce the correct 
value and wishes to be able to do something about 
it if it is wrong. 



RETURN form 
or 

RETURN fn[args] 



The value of the indicated computation is returned 
as the value of the break. 

For example, one might use the EVAL command and 
follow this with RETURN (REVERSE ! VALUE). 



Calls error! and aborts the break, i.e. makes it 
"go away 1 without returning a value. This is a 
useful way to unwind to a higher level break. All 
other errors, including those encountered while 
executing the GO, OK, EVAL, and RETURN commands, 
maintain the break. 



! EVAL 



function is first unbroken, then the break 
expression is evaluated, and then the function is 
rebroken. Very useful for dealing with recursive 
functions. 



!OK 



Function is first unbroken, evaluated, rebroken, 
and then exited, i.e.* !0K is equivalent to ! EVAL 
followed by OK. 



GO 



Function is first unbroken, evaluated, rebroken, 
and exited with value typed, i.e., SEVAL followed 
by 60. 
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unbreaks brkfn , e.g. 

(FOO BROKEN) 

:UB 

FOO 



and FOO is now unbroken 



resets the variable lastpos , which establishes a 
context for the commands ?~, ARCS, BT, BTV, BTV*, 
and EDIT, and IN? described below, lastpos is the 
position of a function call on the push-down 
stack. It is initialized to the function just 
before the call to breakl , i.e. stknth[~l ;BREAK1 ] 

@ treats the rest of the teletype line as its 
argument(s). It first resets lastpos to 
stknth[~l ;BREAKI] and then for each atom on the 
line, 0 searches backward, for a call to that 
atom. The following atoms are treated specially: 

8 do not reset lastpos to 

stkntht>l;BREAKl] but leave it as it 
was, and continue searching from that 
point. 

numbers if negative, move lastpos back that 
number of calls, if positive, forward, 
i.e. reset lastpos to stknth[n ; lastpos ] 

*■ search forward for next atom 

/ the next atom is a number and can be 

used to specify more than one call e.g. 
@ FOO / 3 is equivalent to 
® FOO FOO FOO 

Example : 

if the push-down stack looks like 



BREAK 1 


(13) 


FOO 


<12) 


SETQ 


(11) 


COND 


(10) 


PROG 


(9) 


FIE 


(8) 


COND 


(7) 


FIE 


(6) 


COND 


(5) 


FIE 


(4) 


COND 


(3) 


PROG 


(2) 


FUH 


(1) 



then @ FIE COND will set lastpos to the position 
corresponding to (7); @ © COND will then set 
lastpos to (5); © FUH «- FIE to (4) ; and 
@ FIE / 3 -1 to (3). 

If ® cannot successfully complete a search, it 
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types (fn NOT FOUND), where fn is the name of the 
function for which it was searching. 



When 0 finishes, it types the name of the function 
at lastpos , i.e. stknarn©[ lastpos] 

0 can be used on brkcoms . In this case, the next 
command on brkcoms is treated the same as the rest 
of the teletype line. 



This is a multi-purpose command. Its most common 
use is to interrogate the value(s) of the 
arguments of the broken function, e.g. if FOO has 
three arguments (X Y Zh then typing ?s to a break 
on FOO, will produce: 



?s operates on the rest of the teletype line as 
its arguments. If the line is empty, as in the 
above case, it prints all of the arguments. If 
the user types ?s X (CAR Y), he will see the value 
of X, and the value of (CAR Y). The difference 
between using ?« and typing X and (CAR Y) directly 
to breakl is that ?^ evaluates its inputs as of 
lastpos , i.e. it uses stkeval . This provides a 
way of examing variables or performing 
computations as of a particular point on the 
stack, For example, 0 FOO / 2 followed by ?s X 
will allow the user to examine the value of X in 
the previous call to FOO, etc. 

?s also recognises numbers as refering to the 
correspondingly numbered argument, i.e. it uses 
stkarg in this case. Thus 



will print the name and value of the second 
argument of FIE. 

?s can also be used on brkcoms , in which case the 
next command on brkcoms is treated as the rest of 
the teletype line. For example, if brkcoms is 
(EVAL ?« (X Y) GO), brkexp will be evaluated, the 
values of X and Y printed, and then the function 
exited with its value being printed. 



Prints a backtrace of function names only starting 
at lastpos . (See discussion of 0 above) The 
several nested calls in system packages such as 
break, edit, and the top level executive appear as 
the single entries ««BREAK««, *«EDITOR«*, and 
«*TOP«* respectively. 



:?= 
X = 
Y a 
Z s 



value of X 
value of Y 
value of Z 



:0 FIE 
FIE 
:?= 2 
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BTV 



Prints a backtrace of function names with 
variables beginning at iastpos . 



BTV* Same as BTV except also prints arguments of 

internal calls to eval > (See Section 12) 



BTV! Same as BTV except prints everything on stack, 

(See Section 12). 

BT, BTV, BTV*, and BTV! all permit an optional functional argument which is a 
predicate that chooses functions to be skipped on the backtrace, e.g., BT SUBRP 
will skip all SUBRs, BTV (LAMBDA (X) (NOT (MEMB X FOOFNS )'-))- will skip all but 
those functions on FOOFNS. If used as a brkcom the functional argument is no 
longer optional, i.e. the next brkcom must either be the functional argument, 
or NIL if no functional argument is to be applied. 

For BT, BTV, BTV*, and BTV!, if control-P is used to change a printlevel during 
the backtrace, the printlevel will be restored after the backtrace is 
completed. 

ARGS Prints the names of the variables bound at 

Iastpos , i.e. variables[ Iastpos] (Section 12). 
For most cases , these are the arguments to the 
function entered at that position, i.e. 
arglist[stkname[ Iastpos]]. 



The following two commands are for use only with unbound atoms or undefined 
function breaks (see Section 16). 



form, = fn[args] only for the break following an unbound atom 

error. Sets the atom to the value of the form, or 
function and arguments, exits from the break 
returning that value, and continues the 
computation, e.g. 

U.B.A. 

(F00 BROKEN) 
(COPY FIE) 



sets F00 and goes on. 
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-> expr for use either with unbound atom error, or 

undefined function error. Replaces the expression 
containing the error with expr (not the value of 
expr ) e.g. , 

U.D.F. 

(F001 BROKEN) 
:-> F00 

changes the F001 to F00 and continues the 
computation. 

expr need not be atomic, e.g. 
U.B.A. 

(F00 BROKEN) 
:-> (QUOTE F00) 

For U.D.F. breaks, the user can specify a function 
and initial arguments, e.g. 

U.D.F. 

(MEMBERX BROKEN) 
:-> MEMBER X 

Note that in the case of a U.D.F. error occurring 
immediately following a call to apply , e.g. 
(APPLY X Y) where the value of x is FOO and FOO is 
undefined, or a U.B.A. error immediately following 
a call to eval, e.g. (EVAL X), where the value of 
x is FOO and FOO is unbound, there is no 
expression containing the offending atom. In this 
case, -> cannot operate, so ? is printed and no 
action taken* 



EDIT designed for use in conjunction with breaks caused 

by errors. Facilitates editing the expression 
causing the break: 

NON-NUMERIC ARG ' 
NIL 

(IPLUS BROKEN) 

:EDIT 

IN FOO... 

(IPLUS X Z) 

EDIT 

*(3 Y) 

«OK 

FOO 



and user can continue by typing OK, EVAL, etc. 



-> does not change just brkexp ; it changes the function or expression 
containing the erroneous form. In other words, the user does not have to 
perform any additional editing. 
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This command is very simple conceptually, but complicated in its implementation 
by all of the exceptional cases involving interactions with compiled functions, 
breaks on user functions, error breaks, breaks within breaks, et al . 
Therefore, we shall give the following simplified explanation which will 
account for 90% of the situations arising in actual usage. For those others, 
EDIT will print an appropriate failure message and return to the break* 

EDIT begins by searching up the stack beginning at lastpos (set by @ command, 
initially position of the break) looking for a form, i.e. an internal call to 
eval. Then EDIT continues from that point looking for a call to an interpreted 
function, or to eval . It then calls the editor on either the EXPR or the 
argument to eval in such a way as to look for an expression eg to the form that 
it first found. It then prints the form, and permits interactive editing to 
begin. Note that the user can then type successive Q's to the editor to see 
the chain of superforms for this computation. 

If the user exits from the edit with an OK, the break expression is reset, if 
possible, so that the user can continue with the computation by simply typing 
OK. However, in some situations, the break expression cannot be reset. For 
example, if a compiled function FOO incorrectly called putd and caused the 
error ARG NOT ATOM followed by a break on putd , EDIT might be able to find the 
form headed by FOO, and also find that form in some higher interpreted 
function. But after the user corrected the problem in the FOO-form, if any, he 
would still not have in any way informed EDIT what to do about the immediate 
problem, i.e. the incorrect call to putd . However, if FOO were interpreted 
EDIT would find the putd form itself, so that when the user corrected that 
form, EDIT could use the new corrected form to reset the break expression. The 
tv/o cases are shown below: 



Evaluating the new brkexp will involve reevaluating the form that causes 
the break, e.g. if (PUTD (QUOTE (FOO)) big-computation) were handled by 
EDIT, big-computation would be reevaluated. 



15.12 



ARG NOT ATOM 
(FUM) 

(PUTO BROKEN) 

:EOIT 

IN FIE... 

(FOO X) 

EDIT 

*(2 (CAR X)) 
*OK 

NOTE: BRKEXP NOT CHANGED 
FIE 

: ? = 

U = (FUM) 

:(SETQ U (CAR U)) 

FUM 

:OK 

PUTD 



ARG NOT ATOM 

(PUTD BROKEN) 

:EDIT 

IN FOO... 

(PUTD X) 

EDIT 

*(2 (CAR X)) 

*OK 

FOO 

:OK 

PUTD 



IN? 



similar to EDIT, but just prints parent form, and 
superform, but does not call editor, e.g. 

ATTEMPT TO RPLAC NIL 
T 

(RPLACD BROKEN) 
:IN? 

FOO: (RPLACD X Z) 



Although EDIT and IN? were designed for error breaks, they can also be useful 
for user breaks. For example, if upon reaching a break on his function FOO, 
the user determines that there is a problem in the call to FOO, he can edit the 
calling form and reset the break expression with one operation by using EDIT. 
The following two protocol's with and without the use of EDIT, illustrate this: 
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(FOO BROKEN) 
: ? = 

X = (ABC) 

Y = D 
:BT 

FOO 

SETQ 

COND 

PROG 

FIE 

: EDITF( FIE ) 
EOIT 

*F FOO P 
(FOO V U) 
*(SW 2 3) 
*OK 
FIE 

:(SETQ Y X) 
(A B C) 
:(SETQQ X D) 
D 

:? = 
X = D 

Y = (A B C) 
:OK 

FOO 



find which function 
FOO is called from 

(aborted with fE) 



edit it 



reset X and Y 



(FOO BROKEN) 
:?= 

X = (ABC) 

Y = 0 

:EDIT 

IN FIE... 

(FOO V U) 

EOIT 

*(SW 2 3) 
*OK 

FIE 0 

:OK 

FOO 



check them 



REVERT 



goes back to position lastpos on stack and 
reenters the function called at that point with 

7 

the arguments found on the stack. 



REVERT is useful for continuing a computation in the situation where a bug is 
discovered at some point below where the problem actually occurred. REVERT 

a 

essentially says "go back there and start over." ° 

? prints the names of the break commands. 



6 



8 



x and i have not been changed, but brkexp has. See previous footnote. 

REVERT can also be given the position using the conventions described for @ 
on page 15.8, e.g. REVERT FOO -1 is equivalent to @ FOO -1 followed by 
REVERT. 

REVERT will work correctly if the names or arguments to the function, or 
even its function type, have been changed. 
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Brkcoms 



The fourth argument to breakl is brkcoms , a list of break commands that break! 
interprets and executes as though they were teletype input. One can think of 
brkcoms as another input file which always has priority over the teletype. 
Whenever brkcoms =NIL, breakl reads its next command from the teletype. 
Whenever brkcoms is not NIL, breakl takes as its next command car[brkcoms] and 
sets brkcoms to cdr[brkcoms] For example, suppose the user wished to see the 
value of the variable x after a function was evaluated. He would set up a 
break with brkcoms=(EVAL (PRINT X) OK) , which would have the desired effect. 
The function trace uses brkcoms : it sets up a break with two commands; the 
first one prints the arguments of the function, or whatever the user specifies, 
and the second is the command GO, which causes the function to be evaluated and 
its value printed. 

If brkcoms is not NIL, the value of a break command is not printed. If you 
desire to see a value, you must print it yourself, as in the above example with 
the command (PRINT X). 

Note*, whenever an error occurs, brkcoms is set to MIL, and a full interactive 
break occurs . 



Brkf ile 



The break package has a facility for redirecting ouput to a file. The variable 
brkf ile should be set to the name of the file, and the file must be opened. 



Normally, when a user breaks or traces a function, the value of brkcoms for 
the corresponding call to breakl will be defaulted to NIL. However, it is 
possible to specify a list of break commands, as described in the 
discussion of break and breakl below. 
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All output resulting from brkcoms will be output to brkf ile , e.g. output due to 
TRACE . Output due to user typein is not affected, and will always go to the 
terminal, brkf ile is initially T. 



Breakmacros 

Whenever an atomic command is given breakl that it does not recognise, either 
via brkcoms or the teletype, it searches the list breakmacros for the command. 
The form of breakmacros is ( ... (macro command^ command 2 ... command n ) . ..). 
If the command is defined as a macro, breaki simply appends its definition, 
which is a sequence of commands, to the front of brkcoms , and goes on* If the 
command is not contained in breakmacros , it is treated as a function or 
variable as before. *° 

Example: the command ARGS could be defined by including on breakmacros : 
(ARGS (PRINT (VARIABLES LASTPOS T))) 

Breakresetforms 

If the user is developing programs that change the way a user and INTERLI5P 
normally interact, e.g. change or disable the interrupt or line-editing 
characters, turn off echoing, etc., debugging them by breaking or tracing may 
be difficult, because INTERtISP might be in a 'funny 1 state at the time of the 
break, breakresetforms is designed to solve this problem. The user puts on 
breakresetforms expressions suitable for use in conjunction with resetform 



If the command is not the name of a defined function, bound variable, or 
lispx command, breakl will attempt spelling correction using breakcomslst 
as a spelling list. If spelling correction is unsuccessful, breakl will go 
ahead and call lispx anyway, since the atom may also be a misspelled 
history command. 
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(section 5). When a break occurs, breakl evaluates each expression oh 
breakresetforms before any interaction with the terminal, and saves the values. 
When the break expression is evaluated via an EVAL, OK, or GO, breakl first 
restores the state of the system with respect to the various expressions on 
breakresetforms . When (if) control returns to breakl , the expressions on 
breakresetforms are again evaluated, and their values saved. ° When the break 
is exited via an OK, GO, RETURN, or command, breakl again restores state. Thus 
the net effect is to make the break invisible with respect to the user's 
programs, but nevertheless allow the user to interact in the break in the 
normal fashion. 



15.3 Break Functions 

break 1[ brkexp ; brkwhen ;brkfn ;brkcoms ;brktype] 

is an nlambda . brkwhen determines whether a break 
is to occur. If its value is NIL, brkexp is 
evaluated and returned as the value of breakl . 
Otherwise a break occurs and an identifying 
message is printed using brkfn . Commands are then 
taken from brkcoms or the teletype and 
interpreted. The commands, GO, !GO, OK, !OK, 
RETURN and t, are the only ways to leave breakl . 
The command EVAL causes brkexp to be evaluated, 
and saves the value on the variable lvalue. Other 



11 



12 



i.e. the value of each form is its 'previous state,' so that the effect of 
evaluating the form can be undone by applying car of the form to the value, 
e.g. radix, printlevel , llnelength, setreadtable , interruptchar , etc., all 
have this property. 

Because a lower function might have changed the state of the system with 
respect to one of the these expressions! 
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commands can be defined for breakl via 
breakroacros . brktype is MIL for user breaks, 
INTERRUPT for control-H breaks, and ERRORX for 
error breaks. 

For error breaks, the input buffer is cleared and saved. (For control-H 
breaks, the input buffer was cleared at the time the control-H was typed* see 
Section 16.) In both cases, if the break returns a value, i.e., is not aborted 
via t or control-D, the input buffer will be restored (see Section 14). 

breakO[fn;when;coms] sets up a break on the function fn by redefining 

fn as a call to breakl with brkexp an equivalent 
definition of fn, and when , fn, and corns , as 
brkwhen , brkfn , brkcoms . Puts property BROKEM on 
property list of fn with value a gensyro defined 
with the original definition. Puts property 
BRKINFO on property list of fn with value (BREAKO 
when corns) (For use in conjunction with rebreak ) . 
Adds fn to the front of the list brokenfns . Value 
is fn. 

If fn is non-atomic and of the form ( fnl IN fn2), 
breakQ first calls a function which changes the 
name of fnl wherever it appears inside of fn2 to 
that of a new function, fnl-IN-fn2, which it 
initially defines as fnt . Then breakQ proceeds to 
break on fnl-IN-fn2 exactly as described above. 
This procedure is useful for breaking on a 
function that is called from many places, but 
where one is only interested in the call from a 
specific function, e.g. (RPLACA IN FOO), 
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(PRINT IN FIE), ate. It is similar to breakin 
described below, but can be performed even when 
FiV2 is compiled or blockcompiled, whereas breakin 
only works on interpreted functions. 

If fnl is not found in fn2, breakO returns the 
value (fnl NOT FOUND IN fn2). 

If fnl is found in fn2, in addition to breaking 
fnl-IN-fn2 and adding fnl-IN-fn2 to the list 
brokenfns, breakO adds fnl to the property value 
for the property NAMESCHAN6ED on the property list 
of fnZ and adds the property ALIAS with the value 
(fn2 . fnl) to the property list of fnl-IN-f n2 » 
This will enable unbreak to recognize what changes 
have been made and restore the function fn'2 to its 
original state. 

If fn is nonatomic and not of the above form, 
breakO is called for each member of fn using the 
same values for when , corns , and file specified in 
this call to breakO . This distributivity permits 
the user to specify complicated break conditions 
on several functions without excessive retyping, 
e.g., 

breakO[(F001 ((PRINT PRIN1) IN (F002 F003))); 
(NEQ X T);(EVAL T- (Y Z) OK)] 

will break on FOOl, PRINT-IN-F002 , PRINT-IN-F003 . 
PRIN1-IN-F002 and PRIN1-IN-F003. 

If fn is non-atomic, the value of breakO is a list 
of the individual values. 
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break[x] is a nospread nlambda . For each atomic argument, 

it performs breakO[atom;T]. For each list, it 
performs apply[ BREAK 0 ; list ] . For example, 
breakCFOOl (F002 (GREATERP N 5) (EVAL) ) ] is 
equivalent to break0[FOOl , T] and 

breakO[F002; (GREATERP N 5); (EVAL) ] 

trace[x] is a nospread nlambda > For each atomic argument, 

it performs breakO[atom;T;(TRACE ?» NIL GO)] ia For 
each list argument, car is the function to be 
traced, and cdr the forms the user wishes to see, 
i.e. trace performs: 

breakOC car[ list ] ; T ; 1 ist[ TRACE ; ?« ; cdr[ list ],GO]] 

For example, TRACE(F001 (F002 Y) ) will cause both 
FOOl and F002 to be traced. All the arguments of 
FOOl will be printed; only the value of Y will be 
printed for F002. In the special case that tho 
user wants to see only the value, he can perform 
TRACE((fn)). This sets up a break with commands 
(TRACE ?= (NIL) GO). 

Mote: the user can always call breakO himself to obtain combination of options 
of breakl not directly available with break and trace. These two functions 
merely provide convenient ways of calling breakO , and will serve for most uses. 
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The flag TRACE is checked for in breakl and causes the message 'function : 1 



to be printed instead of (function BROKEN). 
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Breakin 



Breakin enables the user to insert a break, i.e. a call to break! , at a 
specified location in an interpreted function. For example, if foo calls f ie , 
inserting a break in foo before the call to fie is similar to breaking fie . 
However, breakin can be used to insert breaks before or after prog labels, 
particular SETQ expressions, or even the evaluation of a variable. This is 
because breakin operates by calling the editor and actually inserting a call to 
breakl at a specified point inside of the function. 

The user specifies where the break is to be inserted by a sequence of editor 
commands. These commands are preceded by BEFORE, AFTER, or AROUND, which 
breakin uses to determine what to do once €h& editor has found the specified 
point, i.e. put the call to breakl BEFORE that point, AFTER that point, or 
AROUND that point. For example, (BEFORE COND) will insert a break before the 
first occurrence of cond, (AFTER COND 2 1) will insert a break after the 
predicate in the first cond clause, (AFTER BF (SETQ X &)) after the last place 
X is set . Note that (BEFORE TTY: ) or (AFTER TTY: ) permit the user to type in 
commands to the editor, locate the correct point, and verify it for himself 
using the P command if he desires, and exit from the editor with OK,^ breakin 
then inserts the break BEFORE* AFTER, or AROUND that point. 

For breakin BEFORE or AFTER, the break expression is NIL, since the value of 
the break is irrelevant. For breakin AROUND, the break expression will be the 
indicated form. In this case, the user can use the EVAL command to evaluate 
that form, and examine its value, before allowing the computation to proceed. 
For example, if the user inserted a break after a cond predicate, e.g. 



A STOP command typed to TTY: produces the same effect as an unsuccessful 
edit command in the original specification, e.g., (BEFORE CONDD). In both 
cases, the editor aborts, and breakin types (NOT FOUND). 
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(AFTER { EQUAL X Y) ) , he would be powerless to alter the flow of computation if 
the predicate were not true, since the break would not be reached. However , by 
breaking (AROUND (EQUAL X Y)), he can evaluate the break expression, i.e, 
(EQUAL X Y) , look at its value, and return something else if he wished. 

The message typed for a breakin break, is ((fn) BROKEN), where fn is the name 
of the function inside of which the break was inserted. Any error, or typing 
control-E, . will cause the full identifying message to be printed, e.g.' 
(FOO BROKEN AFTER COND 2 1), 

A special check is made to avoid inserting a break inside of an expression 
headed by any member of the list nobreaks , initialized to (GO QUOTE ®), since 
this break would never be activated. For example, if (GO L) appears before the 
label L, breakin (AFTER L) will not insert the break inside of the GO 
expression, but skip this occurrence of L and go on to the next L, in this case 
the label L. Similarly, for BEFORE or AFTER breaks, breakin checks to make 
sure that the break is being inserted at a "safe" place. For example, if the 
user requests a break (AFTER X) in (PROG (SETQ X &) --)• the break will 
actually be inserted AFTER (SETQ X &), and a message printed to this effect, 
e.g. BREAK INSERTED AFTER (SETQ X &). 

break in[ fn ;where ;when ; corns 3 breakin is an n lambda , when and corns are similar 

to when and corns for breakO , except that if when 
is NIL, T is used, where specifies where in the 
definition of fn the call to breakl is to bo 
inserted. (See earlier discussion). 

If fn is a compiled function, breakin returns 
(fn UNBREAKABLE) as its value. 

If fn is interpreted, breakin types SEARCHING . . . 
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while it calls the editor. If the location 
specified by where is not found, breakin typos 
(NOT FOUND) and exits. If it is found, breakin 
adds the property BROKEN-IN with value T, and the 
property 8RK1NF0 with valua (where when corns) to 
the property list of fn, and adds fn to the front 
of the list brokenfns . 

Multiple break points, can be inserted with a 
single call to breakin by using a list of the form 
((BEFORE ...) (AROUND . ..)) for where. It is 
also possible to call break or trace on a function 
which has been modified by breakin , and conversely 
t0 breakin a function which has been redefined by 
a call to break or trace . 

unbreak is a nospread nlambda . It takes an 
indefinite number of functions modified by break , 
trace , or breakin and restores them to their 
original state by calling unbreakO . Value is list 
of values of unbreakO . 

unbreak[ ] will unbreak all functions on brokenfns , 
in reverse order. It first sets brkinfolst to 
NIL. 

unbreak[T] unbreaks just the first function on 
brokenfns , i.e., the most recently broken 
function. 

restores fn to its original state. If fn was not 



15.23 



broken, value is (MOT BROKEN) and no changes are 
made. If fn was modified by breakin , unbreakin is 
called to edit it back to its original state. If 
fn was created from (fnl IN fn2) 9 i.e. if it has & 
property ALIAS,, the function in which fn appears 
is restored to its original state. All dummy 
functions that were created by the break are 
eliminated. Adds property value of BRKINFO to 
(front of) brkinfolst . 

Wote: unbreakO[(fnl IN fn2)] is allowed: unbreakQ 
will operate on fnl~IN«fn2 instead. 

unbreakin[ fn] performs the appropriate editing operations to 

eliminate all changes made by breakin . fn may be 
either the name or definition of a function. 
Value is fn. Unbreakin is automatically called by 
unbreak if fn has property BR0&EN-1N with value T 
on its property list. 

rebreak[x] is an nlambda , nospread function for rebreaking 

functions that were previously broken without 
having to respecify the break information. For 
each function on x P rebreak searches brkinfolst 
for break(s) and performs the corresponding 
operation. Value is a list of values 
corresponding to calls to breakO or breakin . If 
no information is found for a particular function, 
value is (fn - NO BREAK INFORMATION SAVED). 

rebreak[ ] rebreaks everything on brkinfolst , i.e., 
rebreak[ ] is the inverse of unbreakC ]. 
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rebreak[T] rebreaks just the first break on 
brkinfolst , i.e., the function most recently 
unbroken. 

changename[fn;from;to] changes all occurrences of from to to in fn. fn 

may be compiled or blockcompiled. Value is fn if 
from was found, otherwise NIL. Does not perform 
any modifications of property lists. Note that 
from and to do not have to be functions, e.g. they 
can be names of variables, or any other literals. 

virginfn[fn;f Ig] is the function that knows how to restore 

functions to their original state regardless of 
any amount of breaks, breakins, advising, 
compiling and saving exprs, etc. It is used by 
prettyprint , define, and the compiler. If 
f lg =NIL, as for prettyprint , it does not modify 
the definition of fn in the process of producing a 
"clean" version of the definition, i.e. it works 
on a copy. If f Ig sT as for the compiler and 
define , it physically restores the function to its 
original state, and prints the changes it is 
making, e.g. F00 UNBROKEN, FOO UNADVISED, FOO 
NAMES RESTORED, etc. Value is the virgin function 
definition. 

baktrace[posl ;pos2;skipfn;varsf lg;*form*f lgjallflg] prints backtrace from 

post to pos2 . If skipfn is not NIL, and 
skipfn[stkname[pos]] is T„ pos is skipped 
(including all variables). 
varsflg sT for backtrace a la BTV 
varsflg sT, «form«flg sT - BTV* 
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varsflg-T. allflgsT - BTV! 
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SECTION 16 
ERROR HANDLING 



16.1 Unbound Atoms and Undefined Functions 



Whenever the interpreter encounters an atomic form with no binding on the push- 

t 

down list, and whose value contains the atom NOBIND, the interpreter calls 
the function faulteval . Similarly, faulteval is called when a list is 
encountered, car of which is not the name of a function or a function object. 
The value returned by faulteval is used by the interpreter exactly as though it 
were the value of the form. 



faulteval is defined to print either U.S.A., for unbound atom, or U.D.F., for 
undefined function „ and then to call break! giving it the offending form as 

q 

brkexp . Once inside the break, the user can set the atom, define the function, 
return a specified value for the form using the RETURN command, etc., or abort 



All atoms are initialized (when they are created by the read program) with 
their value cells ( car of the atom) NOBIND, their function cells NIL, and 
their property lists ( cdr of the atom) NIL. 



See Appendix 2 for complete description of INTERLISP interpreter. 



If DVIM is enabled (and a break is going to occur), f aul teval also prints 
the offending form (in the case of a U.B.A. , the parent form) and the name 
of the function which contains the form. For example, if FOO contains 
(CONS X FIE) and FIE is unbound, faulteval prints: 

U.B.A. FIE [1n FOO] 1n (CONS X FIE). Note that if DWIM is not enabled, the 
user can obtain this information after he is inside the break via the IN? 
command. 
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the break using the f command. If the break is exited with a value, the 

4 

computation will proceed exactly as though no error had occurred. 



The decision over whether or not to induce a break depends on the depth of 
computation, and the amount of time invested in the computation. The actual 
algorithm is described in detail below in the section on breakcheck . Suffice 
it to say that the parameters affecting this decision have been adjusted 
empirically so that trivial type-in errors do not cause breaks, but deep errors 

dO, . 

16.2 Terminal Initiated Breaks 
Control-H 

Section 15 on the break package described how the user could cause a break when 
a specified function was entered. The user can also indicate his desire to go 
into a break at any time while a program is running by typing control-H. 5 At 
the next point a function is about to be entered, the function interrupt is 
called instead. interrupt types INTERRUPTED BEFORE followed by the function 



A similar procedure is followed whenever apply or apply** are called with an 
undefined function, i.e. one whose f ntyp is NIL. In this case, faul tapply 
is called giving it the function as its first argument and the list of 
arguments to the function as its second argument. The value returned by 
f aultapply is used as the value of apply or apply* -, f aultapply is defined 
to print U.O.F. and then call breakl giving it 
( APPLY (QUOTE fn) QUOTE args)) as brkexp . Once inside the break, the user 
can define the function, return a specified value, etc. If the break is 
exited with a value, the computation will proceed exactly as though no 
error had occurred, f aultapply is also called for undefined function calls 
from compiled code. 

As soon as control-H is typed, INTERLISP clears and saves the input buffer, 
and then rings the bell, indicating that it is now safe to type ahead to 
the upcoming break. If the break returns a value, i.e., is not aborted via 
t or control-D, the contents of the input buffer before the control-H was 
typed will be restored. 
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name, constructs an appropriate break expression and then calls breakl . The 
user can then examine the state of the computation, and continue by typing OK, 
GO or EVAL, and/or retfrom back to some previous point, exactly as with a usor 
break. Control-H breaks are thus always •safe 1 . Note that control-H breaks 
are not affected by the depth or time of the computation. However, they only 
occur when a function is called, since it is only at this time that the system 
is in a "clean" enough state to allow the user to interact. Thus, if a 
compiled program is looping without calling any functions, or is in a I/O wait. 
control-H will not affect it. Control-B, however, will. 

Control-B 

Control-B is a stronger interruption than control-H. It effectively generates 
an immediate error. This error is treated like any other error except that it 
always causes a break, regardless of the depth or time of the computation.^ 
Thus if the function FOO is looping internally, typing control-B will cause the 
computation to be stopped, the stack unwound to the point at which FOO was 
called, and then cause a break. Note that the internal variables of FOO are 
not available in this break, and similarly, FOO may have already produced some 
changes in the environment before the control-B was typed. Therefore whenever 
possible, it is better to use control«H instead of control-B. 

Control-E 

If the user wishes to abort a computation, without causing a break, he should 
type control-E . Control-E does not go through the normal error machinery of 



However, setting helpf lag to NIL will suppress the break. See discussion 
of breakcheck below. 
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scanning the stack, calling breakcheck , printing a message p etc. as described 
below, but simply types a carriage-return and unwinds. 

16.3 Other Types of Errors 

In addition to U.B.A. and U.D.F. errors, there are currently 28 other error 
types in IMTERLISP, e.g. P-STACK OVERFLOW, NON-NUMERIC ARG, FILE NOT OPEN p 
etc. A complete list is given later in this section. When an error occurs, 
the decision about whether or not to break is handled by breakcheck and is the 
same as with U.B.A. and U.D.F. errors. If a break is to occur, the exact 
action that follows depends on the type of error. For example, if a break is 
to occur following evaluation of (RPLACA NIL (ADD1 5)) (which causes an 
ATTEMPT TO RPLAC NIL error), the message printed will be (RPLACA BROKEN), 
brkexp will be (RPLACA U V W), U will be bound to NIL, V to 6, and W to NIL, 
and the stack will look like the user had broken on rplaca himself. Following 
a NON-NUMERIC ARG error, the system will type IN followed by the name of the 
most recently entered function, and then (BROKEN). The system will then 
effectively be in a break inside of this function, brkexp will be a call to 
ERROR so that if the user types OK or EVAL or GO, a ? will be printed and the 
break maintained. However, if the break is exited with a value via the RETURN 

7 

command, the computation will proceed exactly as though no error had occurred. 

16.4 Breakcheck - When to Break 

The decision as to whether or not to induce a break when an error occurs is 
handled by the function breakcheck . The user can suppress all error breaks by 



Presumably the value will be a number, or the error will occur again. 

Breakcheck is not actually available to the user for advising or breaking 
since the error package is block-compiled. 
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setting the variable helpflag to NIL (initially set to T). If helpf lag=T , the 
decision is affected by two factors: the length of time spent in the 
computation, and the depth of the computation at the time of the error. 9 If the 
time is greater than helptime or the depth is greater than helpdepth , 
breakcheck returns T, meaning a break will occur. 

Since a function is not actually entered until its arguments are evaluated, ^ 
the depth of a computation is defined to be the sum of the number of function 
calls plus the number of internal calls to eval . Thus if the user types in the 
expression [MAPC F00 (FUNCTION (LAMBDA (X) (COND ( (NOT (MEMB X FIE)) (PRINT X] 
for evaluation, and FIE is not bound, at the point of the U.B.A. FIE error, two 
functions, mapc and cond , have been entered, and there are three internal calls 
to eval corresponding to the evaluation of the forms 
(COND ((NOT (MEMB X FIE)) (PRINT X))), (NOT (MEMB X FIE)), and (MEMB X FIE)." 
The depth is thus 5. 



breakcheck begins by searching back up the parameter stack looking for an 
errorset . ^ At the same time, it counts the number of internal calls to eval . 
As soon as (if) the number of calls to eval exceeds helpdepth , breakcheck can 
stop searching for errorset and return T, since the position of the errorset is 
only needed when a break is not going to occur. Otherwise 9 breakcheck 



9 
10 

11 
12 



Except that control-B errors always break. 

Unless of course the function does not have its arguments evaluated, i.e. 
is an FEXPR, FEXPR* , CFEXPR, CFEXPR*, FSUBR or FSUBR* . 

For complete discussion of the stack and the interpreter, see Section 12. 

errorsets are simply markers on the stack indicating how far back unwinding 
is to take place when an error occurs, i.e. they segment the stack into 
sections such as that if an error occurs in any section, control returns to 
the point at which the last errorset was entered, from which NIL is 
returned as the value of the errorset . See page 16.15. 
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continues searching until either an errorset is found* u or the top of the stack 
is reached. Breakcheck then completes the depth check by counting the number 
of function calls between the error and the last errorset , or the top of the 
stack. If the number of function calls plus the number of calls to oval 
(already counted) is greater than or equal to helpdepth , initially set to §J 4 
breakcheck returns T. Otherwise, it records the position of the last errorset , 
and the value of errorset 8 & second argument, which is used in deciding whether 
to print the error message,, and returns NIL. 

breakcheck next measures the length of time spent in the computation by 

IS 

subtracting the value of the variable helpclock from the value of (CLOCK 2), 
If the difference is greater than helptime milliseconds, initially set to 1000, 
then a break will occur, i.e., breakcheck returns T, otherwise NIL. The 
variable helpclock is rebound to the current value of (CLOCK 2) for each 
computation typed in to lispx or to a break. 

The time criterion for breaking can be suppressed by setting helptime to NIL 
(or a very big number) , or by binding helpclock to NIL. Note that setting 
helpclock to MIL will not have any effect because helpclock is rebound by lispx 
and by break . 

If breakcheck is NIL, i.e., a break is not going to occur, then if an errorset 
was found, NIL is returned (via retf rom ) as the value of the errorset , after 
first printing the error message if the errorset 's second argument was TRUE. 



13 



14 



15 



If the second argument to the errorset is INTERNAL, the errorset is ignored 
and searching continues. See discussion of errorset , page 16,15. 

Arrived at empirically, takes into account the overhead due to lispx or 
break . 

Whose value is number of milliseconds of compute time . See Section 21 . 
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If there was no errorset 9 the message is printed, and control returns to 
evalgt . This procedure is followed for all types of errors. 



Mote that for all error breaks for which a break occurs, breakl will clear and 
save the input buffer. If the break returns a value, i.e., is not aborted via 
t or control-Dp the input buffer will be restored as described in Section 15. 

16.5 Error Types 

is 

There are currently forty-five error types in the INTERLISP system. They are 
listed below by error number. The error is set internally by the code that 
detects the error before it calls the error handling functions. It is also the 
value returned by errorn if called subsequent to that type of error,, and is 
used by errormess for printing the error message. 

Most error types will print the offending expression following the message, 
e.g. , NON-NUMERIC ARG NIL is very common. Error type 18 (control-8) always 
causes a break (unless helpf lag is NIL). All other errors cause breaks if 
breakcheck returns T. 

0 NONXMEM ( INTERL1SP-10) reference to non-existent memory. 

Usually indicates system is very sick. 

1 Currently not used. 

2 P-STACK OVERFLOW occurs when computation is too deep, either with 

respect to number of function calls, or number of 



Some of these errors are implementation dependent, i.e. appear in 
INTERLISP-10 but may not appear in other INTERLISP systems. 
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variable bindings. Usually because of a non~ 
terminating recursive computation, i.e. a bug, 

3 ILLEGAL RETURN call to return when not inside of an interpreted 

prog * 

4 ILLEGAL ARG - PUTD second argument to putd (the definition) is not 

NIL P a list, or a pointer to compiled code. 

5 ARG NOT ATOM - SET first argument to set, setq , or setqq (name of the 

variable) is not a literal atom. 

6 ATTEMPT TO SET NIL via set or setq 

7 ATTEMPT TO RPLAC NIL attempt either to rplaca or to rplacd NIL with 

something other than NIL. 

8 UNDEFINED OR ILLEGAL GO go when not inside of a prog , or go to nonexistent 

label. 

9 FILE WON'T OPEN From infile or outfile , Section 14. 

10 NON-NUMERIC ARG a numeric function e.g. iplus , itimes , igreaterp , 

expected a number. 



In INTERLISP-10, the garbage collector uses the same stack as the rest of 
the system, so that if a garbage collection occurs when deep in a 
computation, the stack can overflow (particularly if there is a lot of list 
structure that is deep in the car direction). If this does happen, the 
garbage collector will flush the stack used by the computation in order 
that the garbage collection can complete. Afterwards, the error message 
STACK OVERFLOW IN GC - CMPUTATION LOST is printed, followed by a reset[ ], 
i.e. return to top level. 
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11 ATOM TOO LONG In INTERL1SP- 10 , > 100 characters. 

12 ATOM HASH TABLE FULL no room for any more (new) atoms. 

13 FILE NOT OPEN from an I/O function, e.g. read , print , closef . 

14 ARG NOT ATOM e.g. QUt called on a list. 

15 TOO MANY FILES OPEN > 16 including terminal. 

16 END OF FILE from an input function, e.g. read , readc, ratom . 

Note: the file will then be closed. 

17 ERROR call to error . 

18 BREAK control-B was typed. 

19 ILLEGAL STACK ARG a stack function expected a stack position and was 

given something else. This might occur if the 
arguments to a stack function are reversed. Also 
occurs if user specified a stack position with a 
function name, and that function was not found on 
the stack. See Section 12. 



20 FAULT IN EVAL artifact of bootstrap. Never occurs after 

faulteval has been defined as described earlier. 

21 ARRAYS FULL system will first initiate a GC: 1, and if no 

array space is reclaimed, will then generate this 
error. 
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22 DIRECTORY FULL 



( INTERliSP-10) no new files can be created until 
user deletes some old ones and expunges. 



23 FILE NOT FOUND 



file name does not correspond to a file in the 
corresponding directory. Can also occur if file 
name is ambiguous. 



24 



not used. 



25 UNUSUAL CDR ARG LIST a form ends in a non-list other than NIL, e.g. 

(CONS T . 3). 



26 HASH TABLE FULL 



see hash link functions, Section 7. 



27 ILLEGAL ARG 



Catch-all error. Currently used by evala, arg , 
funarg . allocate , rplstrlng, and sfptr . 



28 ARG NOT ARRAY 



elt or seta given an argument that is not a 
pointer to the beginning of an array. 



29 ILLEGAL OR IMPOSSIBLE BLOCK ( INTERLISP-10) from getblk or relblk . 

See Section 21 . 



30 



for internal use. 



31 LISTS FULL 



following a GC: 8, if a sufficient amount of list 
words have not been collected, and there is no un- 
allocated space left in the system, this error is 
generated. 
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32 ATTEMPT TO CHANGE ITEM OF INCORRECT TYPE + 

Before a field of a user-data type is changed, the + 

type of the item is first checked to be sure that * 

it is of the expected type. If not, this error is ♦ 

generated. See section 23. ♦ 

33 ILLEGAL DATA TYPE NUMBER The argument is not a valid user-data type number. * 

See sections 23. ♦ 

34 DATA TYPES FULL All available user-data types have been allocated. + 

See sections 23. ♦ 

35 for internal use. ♦ 

36 for internal use. ♦ 

37 READ-MACRO CONTEXT ERROR Occurs when a read is executed from within a ♦ 

read-macro function and the next token is a ) or a * 

]• See section 14, ♦ 

38 ILLEGAL READTABLE The argument was expected to be a valid readtablo. ❖ 

See section 14. ♦ 

39 ILLEGAL ARG - SWPARRAY (INTERLISP-10) See section 3. ♦ 

40 SWAPBLOCK TOO BIG FOR BUFFER (INTERLISP-10) An attempt was made to ♦ 

swap in a function/array which is too large for ♦ 

the swapping buffer. See setsbsize , section 3. + 

41 ILLEGAL ARG - SETSBSIZE ( INTERLISP-10) The argument to setsbsize must be * 

either NIL or a number between 0 and 128. See + 

section 3. ♦ 
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42 ILLEGAL ARG - SWPPOS 



(INTERLISP-IO) See section 3. 



43 USER BREAK 



Error corresponding to 



'hard 8 



user-interrupt 



character. See page 16.16. 



44 TOO MANY USER INTERRUPT CHARACTERS 



Attempt to enable a user interrupt 



ehartacter when all 9 user channels are currently 



enabled. See page 16.16. 



45 ILLEGAL TERMINAL TABLE The argument was expected to be a valid terminal 

table. See section 14. 

In addition, many system functions, e.g. define, arglist , advise , log, expt , 
etc, also generate errors with appropriate messages by calling error (see page 
16.14). which causes an error of type 17. 

Error handling by error type 

Occasionally the user may want to treat certain error types different than 
others, e.g. always break, never break, or perhaps take some corrective action. 
This can be accomplished via errortypelst . errortypelst is a list of elements 
of the form (n expression), where n is one of the 28 error numbers. After 
breakcheck has been completed, but before any other action is taken, 
errortypelst is searched for an element with the same error number as that 
causing the error. If one is found, and the evaluation of the corresponding 
expression produces a non-NIL value, the value is substituted for the offender, 
and the function causing the error is reeentered. 

For this application, the following three variables may be useful: 
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errorless 



car is the error number, cadr the "offender" e.g. 
(10 NIL) corresponds to NON-NUMERIC ARC NIL error. 



errorpos 



position of the function in which the error 
occurred, e.g. «stkname[ errorpos] might be IPLUS, 
RPLACA, INFILE, etc. 



breakchk 



value of breakcheck , i.e. T means a break will 
occur, NIL means one will not. 



For example, putting 

[10 (AND (NULL (CADR ERRORLESS)) 

(SELECTQ (STKNAME ERRORPOS) 

((IPLUS ADD! SUB1) 0) 
(ITIMES 1) 

(PROGN (SETQ BREAKCHK T) NIL] 

on errortypelst would specify that whenever a NON-NUMERIC ARG - NIL error 
occurred, and the function in question was IPLUS, ADD1, or SUB1 , 0 should be 
used for the NIL. If the function was ITIMES, 1 should be used. Otherwise, 
always break. Note that the latter case is achieved not by the value returned, 
but by the effect of the evaluation, i.e. setting BREAKCHK to T. Similarly, 
(16 (SETQ BREAKCHK NIL) ) would prevent END OF FILE errors from ever breaking. 



16.6 Error Functions 



errorx[ erxm] 



is the entry to the error routines. If erxm sNIL, 
errorn[ ] is used to determine the error-message. 
Otherwise, seterrorn[erxm] is performed, 'setting 1 
the error type and argument. Thus following 
either errorx[(10 T)] or (PLUS T), errorn[ ] is 
(10 T). errorx calls breakcheck , and either 
induces a break or prints the message and unwinds 
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error[messl ;mess2;nobreak] 



help[messl ;mess2] 



to " the last ©rrorset . Mote that errorx can be 
called by any program to intentionally induce an 
error of any type. However, for most 
applications, the function error will be more 
useful. 

The message that is (will be) printed is messl 

(using prinl ), followed by a space if messl is an 

atom, otherwise a carriage return. Then mess2 is 

printed, using print if mess2 is a string, 

otherwise print , e.g., error[ "NON-NUMERIC ARG" ;T] 

will print 

NON-NUMERIC ARG 
T 

and error[FOO;"NOT A FUNCTION" ] will print 
F00 NOT A FUNCTION. (If both messl and me$$2 are 
NIL, the message is simply ERROR.) 

If nobreak sT, error prints its message and then 
calls error! . Otherwise it calls 

errorx[(17 (messl . messZ))], i.e. generates an 
error of type 27, in which case the decision as to 
whether or not to break, and whether or not to 
print a message, is handled as per any other 
error. 

prints messl and mess2 a la error , and then calls 
breakl . If both messl and mess2 are NIL, HELP! is 
used for the message, help is a convenient way to 
program a default condition, or to terminate some 
protion of a program which theoretically the 
computation is never supposed to reach. 
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error! [ ] 



18 



programmable control-E, i.e., immediately returns 
from last errorset or resets. 



reset[ ] 



Programmable control-D, i.e. immediately returns 
to the top level. 



errorn[ ] 



returns information about the last error in the 
form (n x) where n is the error type number and x 
is the expression which was (would have been) 
printed out after the error message. Thus 
following (PLUS T), errorn[ 3 is (10 T). 



errormess[u] 



errorset[u ;v] 



19 



prints message corresponding to an errorn that 
yielded u. For example, errormess[ ( 10 1)3 would 
print 

NON-NUMERIC ARG 
T 

performs eval[u3. Mote that errorset is a lambda- 
type of function, and that its arguments are 
evaluated before it is entered, i.e. errorset[x3 
means eval is called with the value of x. In most 
cases, ersetq and nlsetq (described below) are 
more useful. If no error occurs in the evaluation 
of u, the value of errorset is a list containing 
one element, the value of eval[u3. If an error 
did occur, the value of errorset is NIL. 



18 



19 



Pronounced "error-bang M 



errorset is a subr , so the names "u" and "v" don't actually appear on the 
stack nor will they affect the evaluation. 
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The argument v controls the printing of error 
messages if an error occurs. If vsj 9 the error 
message is printed; if vaNIL it is not. 

If v«INTERNAL, the errorset is ignored for the 
purpose of deciding whether or not to break or 
print a message. However, the errorset is in 
effect for the purpose of flow of control, i.e. if 
an error occurs, this errorset returns NIL. 



ersetq[ersetx] 



nlambda, performs errorset[ersetx;t ], i.e. 
(ERSETQ (FOO)) is equivalent to 

(ERRORSET (QUOTE (FOO)) T). 



nlsetq[nlsetx] 



nlambda , performs errorset[nlsetx;MIL] , 



Interrupt characters 



This section describes how the user can disable and/or redefine INTERLISP 
interrupt characters, as well as defining his own interrupt characters. 
INTERLISP is initialized with 9 interrupt channels which we shall call: HELP, 
PRINTLEVEL, STORAGE, RUBOUT, ERROR, RESET, OUTPUTBUFFER, BREAK, and USER. To 
these are assigned respectively, control-H, control-P, control-S, 
delete/rubout , control-E, control-D, control-O, control-B, and control-U. Each 
of these channels independently can be disabled, or have a new interrupt 2 * 7 
character assigned to it via the function interruptchar described below. In 
addition, the user can enable up to 9 new interrupt channels, and associate 



20 



TENEX requires that interrupt characters be one of control»A, B, ... , Z, 
space, esc(alt-mode), rubout(delete), or break. 
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with each channel an interrupt character and an expression to b© evaluated when 
that character is typed. User interrupts can be either 'hard 1 or 'soft'. A 
'hard 1 interrupt is like control-E or control-D: it takes place as soon as it 
is typed. 22 A soft interrupt is like control-H; it does not occur until the 
next function call. 

interruptchar[char ; typ/f orm;hardf Ig] char is either a character or a 

2P 

terminal interrupt code. 

If typ/form sMIL, char is disabled. If typ/form ^T, 
the current state of char is returned without 
changing it, 23 

If typ/form is a literal atom, it must be the name 
of one of the 9 INTERLISP interrupt channels given 
above: HELP, PRINTIEVEL, . . . USER, interruptchar 
assigns char to that channel, (re&nabling the 
channel if previously disabled). If char was 
previously defined as an interrupt character, that 
interpretation is disabled. 



Hard interrupts are implemented by generating an error of type 43, and 
retrieving the corresponding form from the list userinterruptlst once 
inside of errorx . Soft interrupts are implemented by calling interrupt with 
an appropriate third argument, and then obtaining the corresponding form 
from userinterruptlst . In either case, if a character is enabled as a user 
interrupt, but for some reason it is not found on userinterrupts , an 
UNDEFINED USER INTERRUPT error will be generated. 



The terminal interrupt code for break is 0, for esc is 27, for 
rubout/delete is 28, and for space is 29. The terminal interrupt codes for 
the control characters can be obtained with chconl . 



The current state is an expression which can be given back to , internptchar 
to restore that state. This option is used in connection with undoing 
and resetform. 
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* If typ/form is a list, char is enabled as a user 

* interrupt character, and typ/form is the form that 
+ is evaluated when char is typed. The interrupt 

* will be hard if hardf Ig sT, otherwise soft. Any 

* previous interpretations of char are disabled, 

+ All calls to interruptchar are undoable. In 

+ addition, the value of interruptchar is an 

+ expression which when given back to interruptchar 

+ will restore things as they were before the call 

* to interruptchar . Thus, interruptchar can be used 
+ in conjunction with resetform or resetlst (soq 

* section 5). 

* Note: interruptchar[T] will restore all 1MTERLISP channels to their original 
+ state, and disable all user interrupts. 
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SECTION 17 

AUTOMATIC ERROR CORRECTION - THE DWIM FACILITY 



17.1 Introduction 



A surprisingly large percentage of the errors made by INTERLISP users are of 
the type that could be corrected by another LISP programmer without any 
information about the purpose of the program or expression in question, e.g. 
misspellings, certain kinds of parentheses errors, etc. To correct these types 
of errors we have implemented in INTERLISP a DWIM facility,, short for DO-What- 
I -Mean . DWIM is called automatically whenever an error occurs in the 
evaluation of an INTERLISP expression. DWIM then proceeds to try to correct 
the mistake using the current context of computation plus information about 
what the user had previously been doing, (and what mistakes he had been making) 
as guides to the remedy of the error. If DWIM is able to make the correction, 
the computation continues as though no error had occurred. Otherwise, the 
procedure is the same as though DWIM had not intervened: a break occurs, or an 
unwind to the last errorset, as described in Section 16. The following 
protocol illustrates the operation of DWIM. 



DWIM was designed and implemented by W. Teitelman. It is discussed in 
[Tei2]. 



Currently, DWIM only operates on unbound atoms and undefined function 
errors. 
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Example 



The user defines a function fact of one argument, n. The value of fact[n] is 
to be n factorial. 

*-DEFINEQ( (FACT ( LAMBDA (N) (CONO 

((ZEROP N9 1) ((T (ITIMS N (FACCT 8SUB1 N] 

(FACT) 

Mote that the definition of fact contains several mistakes: itimes and f act 
have been misspelled; the 9 in N9 was intended to be a right parenthesis, but 
the shift key was not depressed; similarly, the 8 in 8SUB1 was intended to be a 
left parenthesis; and finally, there is an extra left parenthesis in front of 
the T that begins the final clause in the conditional. 



-PRETTYPRNT( (FACCT] 

-PRETTYPRINT 

= FACT 

(FACT 

[LAMBDA (N) 
(COND 

( (ZEROP N9 1) 

((T (ITIMS N (FACCT 8SUB1 N]) 

(FACT) 



After defining fact , the user wishes to look at its definition using 
PRETTYPRINT, which he unfortunately misspells .[ 1 ] Since there is no function 
PRETTYPRINT in the system, a U.O.F . error occurs, and DWIM is called, DWIM 
invokes its spelling corrector, which searches a list of functions frequently 
used (by this user) for the best possible match . Finding one that is extremely 
close, DWIM proceeds on the assumption that PRETTYPRNT meant PRETTYPRINT , 
notifies the user of this, [2] and calls prettyprint . 



m 

[23 
[3] 



At this point, PRETTYPRINT would normally print (FACCT NOT PRINTABLE) and exit, 
since facet has no definition. Note that this is not an INTERL1SP error 



condition, so that DWIM would not be called as described above. However, it is 
obviously not what the user meant. 



This sort of mistake is corrected by having prettyprint itself explicitly 
invoke the spelling corrector portion of DWIM whenever given a function with no 
expr definition. Thus with the aid of DWIM, prettyprint is able to determine 
that the user wants to see the definition of the function fact, [3] and proceeds 
accordingly. 



-FACT(3] [4] 

N9 [IN FACT] -> N ) ? YES 

[IN FACT] ( COND -- ((T --))) -> 

(COND -- (T --)) 
ITIMS [IN FACT] -> ITIMES [5] 
FACCT [IN FACT] -> FACT 
8SUB1 [IN FACT] -> ( SUB1 ? YES 
6 

-PP FACT [6] 

(FACT 

[LAMBOA (N) 
(COND 

((ZEROP N) 
1) 

(T (ITIMES N (FACT (SUB1 N]) 

FACT 



The user now calls his function fact . [4] During its execution, five errors 
occur, and DWIM is called five times. [5] At each point, the error is corrected, 
a message printed describing the action taken, and the computation allowed to 
continue as if no error had occurred. Following the last correction, 6 is 
printed, the value of fact(3). Finally, the user prettyprints the new, now 
correct , def inition of fact . [6] 

In this particular example, the user was shown operating in TRUSTING mode, 
which gives DWIM carte blanche for most corrections. The user can also operate 
in CAUTIOUS mode, in which case DWIM will inform him of intended corrections 
before they are made, and allow the user to approve or disapprove of them. For 
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most corrections, if the user does not respond in a specified interval of time, 
DWIM automatically proceeds with the correction, so that the user need 
intervene only when he does not approve* Sample output is given below. Note 
that the user responded to the first, second; and fifth questions; DW1M 
responded for him on the third and fourth. 



*-FACT( 3) 

N9 [IN FACT] -> N ) ? YES [1] 
U.D.F. T [IN FACT] FIX? YES [2] 
[ IN FACT] (COND ((T --))) -> 

(COND — (T •-)) 
IT IMS [IN FACT] -> ITIHES ? . . .YES [3] 
FACCT [IN FACT] -•> FACT ? ...YES [4] 
8SUB1 [IN FACT] -> ( SUB1 ? NO [5] 
U.B.A. 

(8SUB1 BROKEN) 



We have put a great deal of effort into making DWIM 'smart 1 , and experience 
with perhaps fifty different users indicates we have been very successful; DWIM 
seldom fails to correct an error the user feels it should have, and almost 
never mistakenly corrects an error. However, it is important to note that even 
when DWIM is wrong, no harm is done: since an error had occurred, the user 
would have had to intervene anyway if DWIM took no action. Thus, if DWIM 
mistakenly corrects an error, the user simply interrupts or aborts the 
computation, UNDOes the DWIM change using UNDO described in Section 22, and 
makes the correction he would have had to make without DWIM. It is this benign 
quality of DWIM that makes it a valuable part of INTERLISP. 



Except perhaps if DWIM 8 s correction mistakenly caused a destructive 
computation to be initiated, and information was lost before the user could 
interrupt. We have not yet had such an incident occur. 
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17.2 Interaction with DWIM 



DWIM is enabled by performing either DWIM[C], for CAUTIOUS mode, or DWIM[T] for 
TRUSTING mode.^ In addition to setting dwimf lg to T and redefining fan I to va I 
and f aultapply as described on page 17 . 15 P DWIM[C] sets approvef lg to T, whilo 
DWIM[T] sets approvef lg to NIL. The setting of approvef lg determines whether 
or not the user wishes to be asked for approval before a correction that will 
modify the definition of one of his functions. In CAUTIOUS mode, i.e. 
approvef lg =T, DWIM will ask for approval; in TRUSTING mode, DWIM will not. For 
corrections to expressions typed in by the user for immediate execution , 5 DWIM 
always acts as though approvef lg were NIL* I.e. no approval necessary. ^ In 
either case, DWIM always informs the user of its action as described below. 



Spelling Correction Protocol 

The protocol used by DWIM for spelling corrections is as follows: If the 
correction occurs in type-in, print s followed by the correct spelling, 
followed by a carriage-return, and then continue, e.g. 



INTERLISP- arrives with DWIM enabled in CAUTIOUS mode. DWIM can be disabled 
by executing DWIM[ ] or by setting dwimf lg to NIL. See page 17.23. 

Typed into lispx . lispx is used by evalqt and break , as well as for 
processing the editor's E command. Functions that call the spelling 
corrector directly, such as editdefault (Section 9), specify whether or not 
the correction is to be handled as type-in. For example, in the case of 
editdefault , commands typed directly to the editor are treated as type-in, 
so that corrections to them will never require approval. Commands given as 
an argument to the editor, or resulting from macro expansions, or from IF, 
LP, ORR commands etc. are not treated as type-in, and thus approval will be 
requested if approvef lg =T. 

For certain types of corrections, e.g. run-on spelling corrections, 8-9 
errors, etc., dwim always asks for approval, regardless of the setting of 
approvef lg . 
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user types: 
DWIM types i 



*»(SETQ FOO (NCOCN FIE FUH) ) 
=NCONC 



If the correction does not occur in type-in, print the incorrect spelling, 
followed by [IN function~name], ->/ and then the correct spelling, e.g. 
ITIMS [ IN FACT] ~> ITIMES as shown on page 17. 3-/ Then, if approvef Ig ^NIL , 
print a carriage return, make the correction and continue. Otherwise, print a 
few spaces and a ? and then wait for approval. The user then has six options. 
He can : 



1. Type Y; DWIM types ES, and proceeds with the correction. 

2. Type H; DWIM types 0, and does not make the correction. 

3. Type t; DWIM does not make the correction, and furthermore guarantees 
that the error will not cause a break. See-footnote on page 17.15. 

4. Type control~E$ for error correction, this has the same effect as 
typing N. 

5. Do nothing; in which case DWIM will wait a specified interval,^ and if 
the user has not responded, DWIM will type ... followed by the default 
answer . 

6. Type space or carriage-return ; in which case DWIM will ^ wait 
indefinitely. This option is intended for those cases where the user 
wants to think about his answer, and wants to insure that DWIM does 
not get 'impatient 9 and answer for him. 



The appearance of ~> is to call attention to the fact that the user's 
function will be or has been changed. 



Whenever an interaction is about to take place and the user has typed 
ahead, DWIM types several bells to warn the user to stop typing, then 
clears and saves the input buffers, restoring them after the interaction is 
complete. Thus if the user has typed ahead before a DWIM interaction DWIM 
will not confuse his type ahead with the answer to its question, nor will 
his type ahead be lost. 



Equal to dwimwait seconds. DWIM operates by dismissing for 500 
milliseconds, then checking to see if anything has been typed. If not, it 
dismisses again, etc. until dwimwait seconds have elapsed. Thus, there 
will be a delay of at most 1/2 second before DWIM responds to the user's 
answer. 



The default is always YES unless otherwise stated. 
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The procedure for spelling correction on other than INTERLISP errors is 
analogous. If the correction is being handled as type-in, DWIM 
prints = followed by the correct spelling, and returns it to the function that 
called DWIM, e.g. =FACT as shown on page 17.2. Otherwise, DWIM prints the 
incorrect spelling, followed by the correct spelling. Then if approvef lg =N!L , 
DWIM prints a carriage-return and returns the correct spelling. Otherwise, 
DWIM prints a few spaces and a ? and then waits for approval. The user can 
then respond with Y, N, control-E, space, carriage return, or do nothing as 
described . 

Mote that since the spelling corrector itself is not errorset protected, typing 
N and typing control-E may have different effects when the spelling corrector 
is called directly. 11 The former simply instructs the spelling corrector to 
return NIL, and lets the calling function decide what to do next; the latter 
causes an error which unwinds to the last errorset, however far back that may 
be. 

Parentheses Errors Protocol 

As illustrated earlier on page 17.3, DWIM will correct errors consisting of 
typing 8 for left parenthesis and 9 for right parenthesis. In these cases, the 
interaction with the user is similar to that for spelling correction. If the 
error occurs in type-in, DWIM types « followed by the correction, e.g. 



Otherwise, DWIM prints the offending atom, [IN function-name], ~>, the proposed 



The DWIM error correction routines are errorset protection. 



user types: 
DWIM types: 
lispx types: 



-(SETQ FOO SCONS FIE FUM] 
= ( CONS 
(A B C D) 
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correction, a few spaces and "a ?» and- then waits for approval, e.g. 
N9 [IN FACT] -> H ) ? as shown on page 17.3. The user then has the same six 
options as for spelling correction. If the user types Y, DWIM then operates 
exactly the same as when approvef Ig sNIl, i.e. makes the correction and prints 
its message . 

U.D.F. T Errors Protocol 

DWIN corrects certain types of parentheses errors involving a T clause in a 
conditional, namely errors of the form: 

1. (COND (T — ), i.e. the T clause appears outside and immediately 
following the COND; 

2. (COND («- & (T -~))h i.e. the T clause appears inside a previous 
clause; and 

3. (COND ( (T «•«•))), i.e. the T clause has an extra pair of parentheses 
around it. 

If the error occurs in type-in, DWIM simply types T FIXED and makes the 
correction. Otherwise if approvef Ig sNIL, DWIH makes the correction/and prints 
a message consisting of [IN function-name]* followed by one of the above 
incorrect forms of COND, followed by ~>, then on the next line the 
corresponding correct form of the COND, e.g. 



except the waiting time is 3* dwimwait seconds. 

For U.D.F. T errors that are not one of these three types, DWIM takes no 
corrective action at all, i.e. the error will occur. .. 
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[IN FACT] (COND ((T --))) -> 
(CONO (T --)) 



as shown on page 17.3. 

If approver lg =T, DWIM prints U.D.F. T, followed by [IN function-name], several 
spaces, and then FIX? and waits for approval. The user then has the same 
options as for spelling corrections and parenthesis errors. If the user types 
Y or defaults, DWIM then proceeds exactly the same as when approvef Ig ^NIL, i.e. 
makes the correction and prints its message, as shown on page 17.4. 

Having made the correction, DWIM must then decide how to proceed with the 
computation. In case 1, (CONO --) (T --)» DWIM cannot know whether the last 
clause of the COND before the T clause succeeded or not, i.e. if the T clause 
had been inside of the COND, would it have been entered? Therefore DWIM asks 
the user 1 CONTINUE WITH T CLAUSE 1 (with a default of YES). If the user types 
N, DWIM continues with the form after the COND, i.e. the form that originally 
followed the T clause. 

In case 2, (COND (-- & (T --))), DWIM has a different problem. After moving 
the T clause to its proper place, DWIM must return as the value of the COND, 
the value of the expression corresponding to &. Since this value is no longer 
around, DWIM asks the user, 'OK TO REEVALUATE ' and then prints the expression 
corresponding to 6c. If the user types Y, or defaults, DWIM continues by 
reevaluating 6c, otherwise DWIM aborts, and a U.D.F. T error will then occur 
(even though the COND has in fact been fixed). 14 



If DWIM can determine for itself that the form can safely be reevaluated, 
it does not consult the user before reevaluating. DWIM can do this if the 
form is atomic, or car of the form is a member of the list okreevalst , and 
each of the arguments can safely be reevaluated, e.g. 
(SETO X (CONS (IPLUS Y Z) W)) is safe to reevaluate because SETQ, CONS, and 
IPLUS are all on okreevalst. 
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In case 3, (CGND — ((I --)))• there is no problem with continuation, so no 
further interaction is necessary. 

17.3 Spelling Correction 

The spelling corrector is given as arguments a misspelled word (word means 
literal atom), a spelling list (a list of words), and a number: xword , splst , 
and rel respectively. Its task is to find that word on splst which is closest 
to xword , in the sense described below. This word is called a respelltng of 
xword. rel specifies the minimum 'closeness 9 between xword and a respelling. 
If the spelling corrector cannot find a word on splst closer to xword than rel > 
or if it finds two or more words equally close, its value is NIL, otherwise its 
value is the respelling.* 6 

The exact algorithm for computing the spelling metric is described later on 
page 17.20, but brief ly 'closeness ' is inversely proportional to the number of 
disagreements between the two words, and directly proportional to the length of 
the longer word, e.g. PRTTYPRNT is •closer 1 to PRETTYPRINT than CS is to CONS 
even though both pairs of words have the same number of disagreements. The 
spelling corrector operates by proceeding down splst , and computing the 
closeness between each word and xword , and keeping a list of those that are 
closest . Certain differences between words are not counted as disagreements, 
for example a single transposition, e .g . CONS to CNOS, or a doubled letter, 
e.g. CONS to CONSS, etc. In the event that the spelling corrector finds a word 
on splst with no disagreements, it will stop searching and return this word as 
the respelling. Otherwise, the spelling corrector continues through the entire 



The spelling corrector can also be given an optional functional argument, 
fn , to be used for selecting out a subset of splst , i.e. only those members 
of splst that satisfy fn will be considered as possible respellings. 



17.10 



spelling list. Then if it has found one and only one 'closest 1 word, it 
returns this word as the respelling. For example, if xword is VONS, the 
spelling corrector will probably return COMS as the respelling. However, if 
xword is CONZ, the spelling corrector will not be able to return a respelling, 
since CONZ is equally close to both CONS and COND. If the spelling corrector 
finds an acceptable respelling, it interacts with the user as described 
earlier . 

In the special case that the misspelled word contains one or more alt-modes, 
the spelling corrector operates somewhat differently. Instead of trying to 
find the closest word as above, the spelling corrector searches for those words 
on splst that match xword . where an alt-mode can match any number of characters 
(including 0), e.g. FOOS matches F001 and FOO, but not ' N'EWFOO. SFOOS matches 
all three. In this case, the entire spelling list is always searched, and if 
more than one respelling is found, the spelling corrector prints AMBIGUOUS, and 
returns NIL. For example, CONS would be ambiguous if both CONS and COND were 
on the spelling list. If the spelling corrector finds one and only one 
respelling, it interacts with the user as described earlier. 

For both spelling correction and spelling completion, regardless of whether or 
not the user approves of the spelling corrector's choice, the respelling is 
moved to the front of splst . Since many respellings are of the type with no 
disagreements, this procedure has the effect of considerably reducing the time 
required to correct the spelling of frequently misspelled words. 

Synonyms 

Spelling lists also provide a way of defining synonyms for a particular 
context. If a dotted pair appears on a spelling list (instead of just an 
atom), car is interpreted as the correct spelling of the misspelled word, and 
cdr as the antecedent for that word. If car is identical with the misspelled 
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word, the antecedent is returned without any Interaction or approval being 
necessary. For example, the user could make 1FLG synonymous with CL1SPIFTRANFLG 
by adding (IFLG , CtlSPIf TRANFLG) to spellings3 g the spelling list for unbound 
atoms. Similarly; the user could make OTHERWISE mean the same as ELSEIF by 
adding (OTHERWISE . ELSEIF) to clispifwordsplst , or make L be synonymous with 
LAMBDA by adding (L . LAMBDA) to lambdasplst . Hot® that L could also be used 
as a variable without confusion, since the association of L with LAMBDA occurs 
only in the appropriate context. 

Spelling Lists 

Any list of atoms can be used as a spelling list, © 0 g. '. brokenfns , f i'lelst , 
etc. Various system packages have their own spellings lists, e.g. lispxcom s, 
prettycomsplst , clispforwordsplst , editeomsa , etc. These are documented under 
their corresponding sections, and are also indexed under 'spelling lists. 8 In 
addition to these spelling lists, the system maintains, i.e. automatically adds 
to, and occasionally prunes, four lists used solely for spelling correction : 
spellings! , spellings2 p spellings3 , and userwords . 

Spellingsl is a list of functions used for spelling correction when an input is 
typed in apply format, and the function is undefined, e.g. EDTIF(FOO) . 
Spellingsl is initialized to contain defineq , break , makefile , editf , tcompl , 
load , etc. Whenever lispx is given an input in apply format, i.e. a function 
and arguments, the name of the function is added to spellingsl . For example, 
typing CALLS(EDITF) will cause CALLS to be added to spellings! . Thus if the 
user typed CALLS(EDITF) and later typed CALLLS(EDITV) , since spellings! would 



All of the remarks on maintaining spelling lists apply only when DWIM is 
enabled, as indicated by dwimflg sT. 

Only if the function has a -definition. 
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then contain CALLS, DWIM would be successful in correcting CALLLS to CALLS. 



Spellings? is a list of functions used for spelling correction for all other 
undefined functions. It is initialised to contain functions such as addl , 
append , cond , cons , go, list , nconc, print » prog , return , setq , etc. Whenever 
lispx is given a non-atomic form, the name of the function is added to 
spellings? . For example, typing (RETFROH (STKPOS (QUOTE F00) 2)) to a break 
would add retf rom to spellings? . Function names are also added to spellings? 
by def ine , def ineq , load (when loading compiled code), unsavedef , edit f , and 
prettypr int . 

Spellings3 is a list of words used for spelling correction on all unbound 
atoms. Spellings3 is initialized to editnacros , breakmacros , brokenfns , and 
advisedfns . Whenever lispx is given an atom to evaluate, the name of the atom 
is added to spellings3 . ^ Atoms are also added to spellings3 whenever they are 
edited by editv , and whenever they are set via rpaq or rpaqq . For example, 
when a file is loaded, all of the variables set in the file are added to 
spellings3 . Atoms are also added to spellings3 when they are set by a lispx 
input, e.g. typing (SETQ F00 (REVERSE (SETQ FIE --))) will add both FOO and FIE 
to spellings3 . 

Userwords is a list containing both functions and variables that the user has 
referred to e.g. by breaking or editing. Userwords is used for spelling 
correction by arglist , unsavedef , prettyprint , break , editf , advise , etc. 
Userwords is initially NIL. Function names are added to it by def ine . def ineq , 



If CALLLS(EDITV) were typed before CALLS had been 'seen* and added to 
spellings! , the correction would not succeed. However, the alternative to 
using spelling lists is to search the entire oblist, a procedure that would 
make spelling correction intolerably slow. 

Only if the atom has a value other than NOBIND. 
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load , (when loading compiled code, or loading exprs to property lists) 
unsavedef , editf , editv, edltp, prettyprlnt, etc. Variable names are added to 
userwords at the same time as they are added to spellings3 . In addition/ tho 
variable lastv/ord is always set to the last word added to userwords, i.e. the 
last function or variable referred to by the user, and the respelling of NIL is 
defined to be the value of lastword .' Thus, if the user has just defined a 
function, he can then edit it by simply typing EDITF ( ), or prettyprint it by 
typing PP( ) . 

Each of the above four spelling lists are divided into two sections separated 
by a NIL. The first section contains the "permanent 1 words; the second section 
contains the temporary words. Mew words are added to the corresponding 
spelling list at the front of its temporary section. (If the word is already 
in the temporary section, it is moved to the front of that section; if the word 
is in the permanent section* no action is taken.) If the length of the 
temporary section then exceeds a specified number, the last (oldest) word in 
the temporary section is forgotten, i.e. deleted. This procedure prevents the 
spelling lists from becoming cluttered with unimportant words that are no 
longer being used, and thereby slowing down spelling correction time. Since 
the spelling corrector moves each word selected as a respelling to the front of 
its spelling list, the word is thereby moved into the permanent section. Thus 
once a word is mispelled and corrected, it is considered important and will 
never be forgotten. 

The maximum length of the temporary section for spellings! , spellings2 , 
spellings3 and userwords is given by the value of ^spellings! , ^spellingsZ, 
#spellings3 , and ^userwords , initialized to 30, 30, 30, and 60 respectively. 



Except that functions added to spellingsi or spellings2 by lispx are always 
added to the end of the permanent section. — ~ 
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Using these values, the average length of time to search a spelling list for 

2.1 

one word is about 4 milliseconds. 



17.4 Error Correction 

As described in Section 16, whenever the interpreter encounters an atomic form 
with no binding, or a non-atomic form car of which is not a function or 
function object, it calls the function faulteval . Similarly, when apply is 
given an undefined function, it calls faultapply . When DWIM is enabled, 
faulteval and faultapply are redefined to first call dwimblock , a part of the 
DWIM package. If the user aborts by typing control-E, or if he indicates 
disapproval of DWIH.'s intended correction by answering N as described on page 

op 

17.6, or if DWIM cannot decide how to fix the error, dwimblock returns NIL ♦ 
In this case, faulteval and faultapply proceed exactly as described in Section 
16, by printing a U.B.A. or U.D.F. message, and going into a break if the 
requirements of breakcheck are met, otherwise unwinding to the last errorset . 

If DWIM can (and is allowed to) correct the error, dwimblock exits by 
performing reteval of the corrected form, as of the position of the call to 
faulteval or faultapply . Thus in the example at the beginning of the chapter, 
when DWIM determined that ITIMS was ITIMES misspelled, DWIM called reteval with 
(ITIMES N (FACCT 8SUB1 N ) ) . Since the interpreter uses the value returned by 
f aulteval exactly as though it were the value of the erroneous form, the 
computation will thus proceed exactly as though no error had occurred. 



If the word is at the front of the spelling list, the time required is only 
1 millisecond. If the word is not on the spelling list, i.e. the entire 
list must be searched, the time is proportional to the length of the list; 
to search a spelling list of length 60 takes about 7 milliseconds. 



If the user answers with t„ (see page 17.6) dwimblock is exited by 
performing re teval[ FAULTEVAL ; ( ERROR ! )], i.e. an error is generated at the 
position of the call to faulteval . 
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In addition to continuing the computation, DWIM also repairs the cause of the 
error whenever possible. 2 ^ Thus in the above example, DWIM also changed (with 
rplaca) the expression (ITIMS N (FACCT 8SUBI N) ) that caused the error. 

Error correction in DWIM is divided into three categories: unbound atoms, 
undefined cars of form, and undef ined function in apply . Assuming that the 
user approves if he is asked* the action taken by DWIM for the various types of 
errors in each of these categories is summarized below. The protocol of DWIM's 
interaction with the user has been described earlier. 



Unbound Atoms 



1. If the first character of the unbound atom is \ DWIM assumes that the user 
( intentionally) typed *atom for ( QUOTE atom) and makes the appropriate 
change. No message is typed, and no approval requested. 

If the unbound atom is just 1 itself, -DWIM assumes the user wants the next 
expression quoted, e.g. (CONS X '(ABC)) will be changed to 
(CONS X (QUOTE (A B C) ) ) . Again no message will be printed or approval 
asked. (If no expression follows the 1 „ DWIM gives up.) 

2. If CLISP (Section 23) is enabled, and the atom is part of a CUSP 
construct, the CLISP transformation is performed and the result returned, 
e.g. N - 1 is transformed to (SUB1 N) . 

3. If the atom contains an 8, DWIM assumes the 8 was intended to be a left 
parenthesis, and calls the editor to make appropriate repairs on the 
expression containing the atom. DWIM assumes that the user did not notice 
the mistake, i.e. that the entire expression was affected by the missing 
left parenthesis. For example, if the user types 

(5ETQ X (LIST (CONS SCAR Y) (CDR I)) Y), the expression will be changed to 
(SETQ X (LIST (CONS (CAR Y) (CDR Z)) Y) ) . 

The 8 does not have to be the first character of the atom, e.g. DWIM will 
handle (CONS X8CAR Y) correctly. 

4. If the atom contains a 9, DWIM assumes the 9 was intended to be a right 
parenthesis and operates as In number 3. 

5. If the atom begins with a 7, the 7 is treated as a e.g. 7FOO becomes 
■FOO, and then (QUOTE FOO). 



If the user's program had computed the form and called eval , e.g. performed 
(EVAL (LIST X Y) ) and the value of x was a misspelled function ; it would 
not be possible to repair the cause of the error, although DWIM could 
correct the misspelling each time it occurred. 
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6. If the atom is an edit command (a member of editcomsa ) , and the error 
occurred in type-in, the effect is the same as though the user typed 
EDXTF()p followed by the atom, i.e. DWIN assumes the user wants to be in 
the editor editing the last thing he referred to. Thus, if the user 
defines the function foo and then types P, he will see = F00, followed by 
EDIT, followed by the printout associated with the execution of the P 
command, followed by *, at which point he can continue editing £00. 

7. If dwimuserfn sT, DWIN calls dwimuserfn , and if it returns a non-NIL value, 
DWIN returns this value, dwimuserfn is discussed below, 

8. If the unbound atoms occurs in a function, DWIN attempts spelling 
correction using as a spelling list the list of lambda and prog variables 
of the function. 

9. If the unbound atom occurred in a type-in to a break P DWIM attempts 
spelling correction using the lambda and prog variables of the broken 
f unction . 

10. Otherwise, DWIN attempts spelling correction using spellings3 . 
If all fail, DWIM gives up. 



Undefined car of Form 

1. If car of the form is T, DWIN assumes a misplaced T clause and operates as 
described on page 17.8. 

2. If car of the form is F/L, DWIM changes the F/L to 
FUNCTION( LAMBDA, e.g. (F/L (Y) (PRINT (CAR Y) ) ) is changed to 
(FUNCTION (LAMBDA (Y) ( PRINT (CAR Y ) ) ) . No message is printed and no 
approval requested. If the user omits the variable list, DWIM supplies 
(X), e.g. (F/L (PRINT (CAR X))) becomes 

(FUNCTION (LAMBDA (X) (PRINT (CAR X)))). DWIN determines that the user has 
supplied the variable list when more than one expression follows F/L, car 
of the first expression is not the name of a function, and every element in 
the first expression is atomic. For example, DWIM will supply (X) when 
correcting (F/L (PRINT (CDR X)) (PRINT (CAR X))). 

3. If car of the form is IF, if, or one of the CLISP iterative statement 
operators, e.g. FOR, WHILE, DO et al, the indicated transformation is 
performed, and the result returned as the corrected form. 

4- If car of the form has a function definition, DWIN attempts spelling 
correction on car of the definition using as spelling list the value of 
lanbdasplst , initially (LAMBDA NLAMBDA) . 

5. If car of the form has an EXPR property, DWIN prints car of the form, 
followed by 'UNSAVED ' , performs an unsavedef , and continues. No approval 
is requested. 

6. If car of the form has a property FILEDEF, the definition is to be found on 



The user may wish to add to lanbdasplst if he elects to define new 
'function types 1 via an appropriate dwimuserfn . For example, the QLAHBDAs 
of SRI 's QLISP are handled in this way. 
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a file. If the value of the property is atomic, the entire file is to be 
loaded. If a list, car is the name of the. file and cdr the relevant 
functions, and loadfns will be used. DWIM first checks to see if the file 
appears in the attached directory, <NEWLXSP> 's directory, or <LXSP> 1 s 
directory, and if found, types "SHALL I LOAD" followed by the file name or 
list of functions. If the user approves,, DWIM loads the function(s) or 
file, and continues the computation. edita , breakdown , circlm aker , 
cplists , and the pattern match compiler and record capability of CUSP are 
implemented in this fashion. 

7. If CLISP is enabled, and car of the form is part of a CUSP construct, the 
indicated transformation is performed, e.g. (N«-N-l) becomes 
(SETQ N (SUB1 N) ) . 

8 * If car of the form contains an 8, DWIM assumes a left parenthesis was 
intended e.g. (C0NS8CAR X) . 

9. If car of the form contains a 9, DWIM assumes a right parenthesis was 
intended. 

10. If car of the form is a list, DWIM attempts spelling correction on caar of 
the form using larobdasplst as spelling list. If successful, DWIM returns 
the corrected expression itself. 

11. If car of the form is a small number, and the error occurred in type-in, 
DWIM assumes the form is really an edit command and operates as described 
in case 6 of unbound atoms. 

12. If car of the form is an edit command (a member of editcomsl ) , DWIM 
operates as in 1L 

13. If dwinuserfn gT, dwimuserfn is called, and if it returns a non-NIL value, 
DWIM returns this value. 

14. If the error occurs in a function, or in a type-in while in a break, DWIM 
checks to see if the last character in car of the form is one of the lambda 
or prog variables, and if the first n°l characters are the name of a 
defined function, and if so makes the corresponding change, e.g. 
(MEMBER* Y) will be changed to (MEMBER X Y) , The protocol followed will be 
the sane as for that of spelling correction, e.g. if approvef lg =T , DWIM 

. will type MEMBERX [IN F00] -> MEMBER X? 

15. Otherwise, DWIM attempts spelling correction using spellings2 as the 
s p e 1 1 i n g 1 i s t . ^ ~~ 

If all fail, DWIM gives up. 



Undefined Function in Apply 

1. If the function has a definition, DWIM attempts spelling correction on car 
of the definition using lambdasplst as spelling list. 

2. If the function has an EXPR property, DWIM prints its name followed by 
• UNSAVED 1 , performs an unsavedef and continues. No approval is requested. 

3. If the function has a property FILEDEF, DWIM proceeds as in case 6 of 
undefined car of form. 

4. If the error resulted from type-in, and CLISP is enabled, and the function 
name contains a CLISP operator, DWIM performs the indicated transformation, 
e.g. the user types FOCMAPPEND FIE FUM). 



17.18 



5. If the function name contains an 8, DWIM assumes a left parenthesis was 
intended, e.g. EDIT8F00]. 

6. If the 'function' is a list, DWIM attempts spelling correction on car of 
the list using lanbdasplst as spelling list. 

7. If the function is a number and the error occurred in type-in, DWIM assumes 
the function is an edit command, and operates as described in case 6 of 
unbound atoms, e.g. the user types (on one line) 3 -1 P. 

8. If the function is the name of an edit command (on either editcomsa or 
editconsl ) , DWIM operates as in 7, e.g. user types F COND. 

9. If dwinuserfn =T, dwimuserfn is called, and if it returns a non-NIL value, 
this value is treated as the form used to continue the computation, i.e. it 
will be ei/oi-ed. 

10. Otherwise DWIM attempts spelling correction using spellingsl as the 
spelling list, 

11. Otherwise DWIM attempts spelling correction using spellings2 as the 
spelling list. 

If all fail, DWIM gives up. 



17.5 DWIMUSERFN 

Dwimuserfn provides a convenient way of adding to the transformations that DWIM 
performs, e.g., the user might want to change atoms of the form $X to 
(QA4L00KUP X). The user defines dwimuserfn as a function of no arguments, and 
then enables it by setting dwimuserfn to T. DWIM will call dwimuserfn before 
attempting spelling correction, but after performing its other transformations, 
e.g. F/L, 8, 9, CLISP, etc. If dwimuserfn returns a non-NIL value, this value 
is treated as a form to be evaluated and returned as the value of f aulteval or 
f aultapply . Otherwise, if dwimuserfn returns NIL, DWIM proceeds as when 
dwimuserfn is not enabled, and attempts spelling correction. Note that in the 
event that dwimuserfn is to handle the correction, it is also responsible for 
any modifications to the original expression, i.e. DWIM simply takes its value 
and returns it. 

In order for dwimuserfn to be able to function, it needs to know various things 
about the context of the error. Therefore, several of DWIM's internal 
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variables have been made SPECVARS (See Section 18) and are therefore "visible" 
to dwimuserfn . Below are a list of those variables that may be useful. 



faultx for unbound atoms and undefined car of form, 

Taultx is the atom or form. For undefined 
functions in apply , faultx is the name of the 
function. 

faultargs for undefined functions in apply ,, faultargs is the 

list of arguments. 

faultapplyf Ig Is T for undefined functions in apply . (Since 

faultargs may be Nil, faultapplyf Ig is necessary 
to distinguish between unbound atoms and undefined 
function in apply .,- since faultx is atomic in both 
cases) . 



tail 

parent 

type-in? 
faultfn 

dwimifyf Ig 
expr 



for unbound errors, tail is the tail car of which 
is the unbound atom. Thus dwimuserfn can replace 
the atom by another expression by performing 
(/RPLACA TAIL expr) 

for unbound atom errors, parent is the form in 
which the unbound atom appears, i.e. tail is a 
tail of parent . 

true if error occurred in type-in. 

name of function in which error occurred, 
( faultfn is TYPE-IN when the error occurred in 
type-in, and EVAL or APPLY when the error occurred 
under an explicit call to EVAL or APPLY). 

true if error was encountered during dwlmifying as 
opposed to during running the program. 

definition of faultfn , or argument to eval , i.e. 
the superform in which the error occurs. 



17,6 Spelling Corrector Algorithm 

The basic philosophy of DWIM spelling correction is to count the number of 
disagreements between two words, and use this number divided by the length of 
the longer of the two words as a measure of their relative disagreement . One 
minus this number is then the relative agreement or closeness. For example, 
CONS and CONX differ only in their last character. Such substitution errors 
count as one disagreement, so that the two words are in 75% agreement. Most 
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calls to the spelling corrector specify rel=70, ° so that a single substitution 
error is permitted in words of four characters or longer. However, spelling 
correction on shorter words is possible since certain types of differences such 
as single transpositions are not counted as disagreements. For example, AMD 
and NAD have a relative agreement of 100. 

The central function of the spelling corrector is chooz . chooz takes as 
arguments: a word, a spelling list, a minimum relative agreement, and an 
optional functional argument, xword , splst , rel , and fn respectively. 

chooz proceeds down splst examining each word. Words not satisfying fn, or 

those obviously too long or too short to be sufficiently close to xword are 

immediately rejected. For example, if rels70, and xword is 5 characters long, 

P7 

words longer than 7 characters will be rejected. 

If tword, the current word on splst , is not rejected, chooz computes the number 
of disagreements between it and xword by calling a subfunction, skor . 

skor operates by scanning both words from left to right one character at a 
time. Characters are considered to agree if they are the same characters; or 



Integers between 0 and 100 are used instead of numbers between 0 and 1 in 
order to avoid floating point arithmetic. 

fnsNIL is equivalent to fns( LAMBDA NIL T). 



Special treatment is necessary for words shorter than xword , since doubled 
letters are not counted as disagreements. For example, CONNSSS and CONS 
have a relative agreement of 100. (Certain teletype diseases actually 
produce this sort of stuttering.) chooz handles this by counting the number 
of doubled characters in xword before it begins scanning splst , and taking 
this into account when deciding whether to reject shorter words. 



skor actually operates on the list of character codes for each word. This 
list is computed by chooz before calling skor using dchcon, so that no 
storage is used by the entire spelling correction process. 
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appear on the same teletype key (i.e. a shift mistake), for example, * agrees 
with : , 1 with 1 , 29 etc.; or if the character in xword is a lower case version 
of the character in tword. Characters that agree are discarded, and the 
skoring continues on the rest of the characters in xword and tword . 

If the first character in xword and tword do not agree, skor checks to see if 
either character is the same as one previously encountered, and not accounted- 
for at that time. (In other words, transpositions are not handled by 
lookahead, but by lookback.) A displacement of two or fewer positions is 
counted as a tranposition ; a displacement by more than two positions is counted 
as a disagreement. In either case, both characters are now considered as 
accounted for and are discarded, and skoring continues. 

If the f irst character in xword and tword do not agree, and neither are equal 
to previously unaccounted-for characters, and tword has more characters 
remaining than xword , skor removes and saves the first character of tword , and 
continues by comparing the rest of tword with xword as described above. If 
tword has the same or fewer characters remaining than xword , the procedure is 
the same except that the character is removed from xword . In this case, a 
special check is first made to see if that character is equal to the previous 
character in xword , or to the next character in xword , i.e. a double character 
typo, and if so, the character is considered accounted-f or, and not counted as 



For users on model 33 teletypes, as indicated by the value of modc!33f Ig 
being T, @ and P appear on the same key, as do L and /, H and L, and 0 and 
and DWIM will proceed accordingly. The initial value for model33f Ig is 
NIL. Certain other terminals, e.g. Anderson Jacobs terminal, have keyboard 
layouts similar to the model 33, i.e. N on same key as t , etc. In this 
case, the user might also want to set mode!33flg to T. 

Whenever more than two characters in either xword or tword are unaccounted 
for, skoring is aborted, i.e. xword and tword are considered to disagree. 
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a disagreement. 



When skor has finished processing both xword and tword in this fashion e tho 
value of skor is the number of unaccounted-for characters, plus the number of 
disagreements, plus the number of tranpositions, with two qualifications: (1) 
if both xword and tword have a character unaccounted-for in the same position, 
the two characters are counted only once, i.e. substitution errors count as 
only one disagreement, not two; and (2) if there are no unaccounted-for 
characters and no disagreements, transpositions are not counted. This permits 
spelling correction on very short words, such as edit commands, e.g. 
XRT->XTR. 32 



17.7 DVIM Functions 
dwimC x ] 



dwimify[x] 



If x=NIL, disables DWIM; 
enables DWIM in cautious 
If xsT, enables DWIM in 
TRUSTING. For all other 
error. 

x is a form or the name 
performs all corrections 



value is NIL. If x=C , 
mode; value is CAUTIOUS. 

trusting mode; value is 
values of x, generates an 

of a function, dwimify 
and transformations that 



In this case, the 'length* of xword is also decremented. Otherwise making 
xword sufficiently long by adding double characters would make it bo 
arbitrarily close to tword , e.g. XXXXXX would correct to PP. 



Transpositions are also not counted when f astypef lg sT, for example, IPULX 
and IPLUS will be in 80% agreement with f astypef lg =T, only 60% with 
f astypef lg sNIL. The rationale behind this is that transpositions are much 
more common for fast typists, and should not be counted as disagreements, 
whereas more deliberate typists are not as likely to combine tranpositions 
and other mistakes in a single word, and therefore can use more 
conservative metric, fastypef lg is initially NIL. 
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would occur if x were actually run. dwimify is 
* 

undoable. 



DW edit macro, dwimifies current expression. 

addspell[x;splst ;n] Adds x to one of the four spelling lists as 

follows: 33 

if splst sNIU adds x to userwords and to 
spellings2 . Used by def ineq . 

If splst sQ, adds x to userwords . Used by load 

when loading exprs to property lists. 

If splst sl , adds x to spellingsl (at end of 

permanent section). Used by lispx . 

if splst s2 p adds x to spellings2 (at end of 

permanent section). Used by lispx . 

If splst s3, adds x to userwords and spellings3 . 



splst can also be a spelling list P in which case n 
is the (optional) length of the temporary section. 

addspell sets lastword to x when splst «NIL t " 0 or 
3. 

If x is not a literal atom, addspell takes no 
action. 



S3 

If x is already on the spelling list, and in its temporary section* 
addspell moves x to the front of that section. See page 17.14 for complete 
description of algorithm for maintaining spelling lists. 
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misspelled?[xword;rel ;splst ;f Ig; tail ;fn] 

If xword =NIL or alt-mode, misspol led? 
prints s followed by the value of lastword , and 
returns this as the respelling, without asking for 
approval. Otherwise, misspelled? checks to see if 
xword is really misspelled, i.e. if fn applied to 
xword is true, or xword is already contained on 
splst . In this case, misspelled? simply returns 
xword . Otherwise misspelled? computes and returns 
f ixspell[ xword ;rel ; splst ; fig ; tail ;fn] 

f ixspell[ xword; r el ; splst ; fig; tail ;fn ;tteflg) 34 

The value of f ixspell is either the respelling of 
xword or NIL. f ixspell performs all of the 
interactions described earlier, including 
requesting user approval if necessary* 

If xword sNIl or $ (alt-mode), the respelling is 
the value of lastword , and no approval is 
requested. 

If f lg sNIL, the correction is handled in type-in 
mode, i.e. approval is never requested, and xword 
is not typed. If f lg =T, xword is typed (before 
the = ) and approval is requested if approver lg =T '. 

If tail is not NIL, and the correction is 
successful, car of tail is replaced by the 



f ixspell has some additional arguments, for internal use by DWIM. 
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respelling (using /rplaca) . . In addition, f ixs poll 
will correct misspellings caused by running two 
words together, . In this case, car of tail is 
replaced by the two words, and the value of 
f ixspell is the first one. For example, if 
f ixspell is called to correct the edit command 
(HOVE TO AFTERCOND 3 2) with tail =( AFTERCOND 3 2), 
tail would be changed to (AFTER COND 2 3), and 
f ixspell would return AFTER (subject to user 
approval where necessary).^ 



If tief lg sT and a tie occurs, i.e. more than one 
word on splst is found with the same degree of 
'closeness 1 , the first word is taken as the 
correct spelling. If tief Ig ^NIL and a tie occurs, 
f ixspell returns MIL, i.e. no correction. If 
tief Ig sALL, the value of f ixspell is a list of the 
respellings (even if there is only one ) , and 
"f ixspell will not perform any interaction with the 
user, nor modify tail , the idea being that the 
calling program will handle those tasks. 

The time required for a call to f ixspell with a spelling list of length 60 when 
the entire list must be searched is .5 seconds. If f ixspell determines that 



35 



36 



In this case, user approval is always requested. In addition, if the first 
word contains either fewer than 3 characters, or fewer characters than the 
second word, the default will be N . 1 Run-on 1 spelling corrections can be 
suppressed by setting the variable runonf Ig to NIL (initially T) . 

If t a i 1 s T , f ixspell will also perform run-on corrections, returning a 
dotted pair of the two words in the event the correction is of this type. 
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the first word on the spelling list is the respelling and does not need to 
search any further, the time required is .02 seconds. In other words, the time 
required is proportional to the number of words with which xword is compared, 
with the time for one comparison, i.e. one call skor , being roughly .01 seconds 
(varies slightly with the number of characters in the words being compared.) 

The function chooz is provided for users desiring spelling correction without 
any output or interaction: 
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chooz[xword;rel;splst;tail; ;fn;tieflg] 37 The value of chooz is the 

corrected spelling of xword ° or MIL; chooz 
performs no interaction and no output. vol , 
splst , tail , teif Ig , and fn are as described under 
fixspell above. If tail is not NIL and the 
misspelling consists of running two words 
together, e.g. (BREAKFOO) for (BREAK FOO), the 
value of choos will be a dotted pair of the two 
words, e.g. (BREAK . F00). 

fncheck[ fn ;nomessf lg;spellf Ig] The task of fncheck is to check whether fn is 

the name of a function and if not, to correct its 
spelling. 9 If fn is the name of a function or 
spelling correction is successful, fncheck adds 
the (corrected) name of the function to userwords 
using addspell , and returns it as its value. 

nomessf Ig informs fncheck whether or not the 
calling function wants to handle the unsuccessful 
case: if nomessf Ig is T p fncheck simply returns 
NIL, otherwise it prints fn NOT A FUNCTION and 
generates a non-breaking error. 



07 

chooz has some additional arguments, for internal use by DWIM. 
chooz does not perform spelling completion, only spelling correction. 



38 



39 



Since fncheck is called by many low level functions such as arglist , 
unsavedef , etc., spelling correction only takes place when dwimf lg gT, so 
that these functions can operate in a small IMTERLISP system which does not 
contain DWIM. 
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fncheck calls misspelled? to perform spelling 
correction, so that if fn-NIL , the value of 
lastword will be returned, spellf Ig corresponds 
to misspelled? B s fourth argument , f Ig . If 
spellf Ig sT, approval will be asked if DWIM was 
enabled in CAUTIOUS mode, i.e. if approvef Ig aT . 

f ncheck is currently used by arglist , unsavedef , prettyprint , breakO , breakin » 
chngnm , advise , printstructure , f irstfn , lastfn , calls , and edita. For 
example, breakO calls fncheck with nomessf lg «T since if fncheck cannot produce 
a function, breakO wants to define a dummy one. printstructure however calls 
fncheck with nomessf lg =NIL, since it cannot operate without a function. 

Many other system functions call misspelled? or f ixspell directly. For 
example, breakl calls f ixspell on unrecognized atomic inputs before attempting 
to evaluate them, using as a spelling list a list of all break commands. 
Similarly, lispx calls f ixspell on atomic inputs using a list of all lispx 
commands. When unbreak is given the name of a function that is not broken, it 
calls f ixspell with two different spelling lists, first with brokenfns , and if 
that fails, with userwords . makefile calls misspelled? using f ilelst as a 
spelling list. Finally, load , bcompl, brecompile , tcompl , and recompile all 
call misspelled ? if their input file(s) won't open* 
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SECTION 18 
THE COMPILER AND ASSEMBLER 1 



18.1 The Compiler 

The compiler is available in the standard INTERLISP system. It may be used to 
compile individual functions as requested or all function definitions in a 
standard format LOAD file. The resulting code may be stored as it is compiled, 
so as to be available for immediate use, or it may be written onto a file for 
subsequent loading. The compiler in INTERLISP-10 also provides a means of 
specifying sequences of machine instructions via ASSEHBLE. 

The most common way to use the compiler is to compile from a symbolic 
( prettydef ) f ile, producing a corresponding file which contains a set of 
functions in compiled form which can be quickly loaded. An alternate way of 
using the compiler is to compile from functions already defined in the user's 
IMTERLISP system. In this case, the user has the option of specifying whether 
the code is to be saved on a file for subsequent loading, or the functions 
redefined, or both. In either case, the compiler will ask the user certain 
questions concerning the compilation. The first question is: 



The INTERLISP- 10 compiler itself, i.e. the part that actually generates 
code, was written and documented by, and is the responsibility of A.R, 
Hartley. The user interfaces, i.e. tcompl , recompile , bcompl , and 
brecompile , were written by W. Teitelman. 
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LISTING? 



The answer to this question controls the generation of a listing and is 
explained in full below. However, for most applications, the user will want to 
answer this question with either ST or F, which will also specify an answer to 
the rest of the questions which would otherwise be asked. ST means the user 
wants the compiler to STore the new definitions; F means the user is only 
interested in compiling to a File, and no storing of definitions is performed. 
In both cases, the compiler will then ask the user one more question: 

OUTPUT FILE: 

to which the user can answer: 

N or NIL no output file. 

File name file is opened if not already opened, and compiled code 
is written on the file. 

Example: 

-COMPILE* (FACT FACT1 FACT2)) 
LISTING? ST 
OUTPUT FILE: FACT.COM 
(FACT COMPILING) 

(FACT REDEFINED) 2 



(FACT2 REDEFINED) 
(FACT FACT1 FACT2) 



compiler printout and error messages are explained on page 18.49-53. 
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This process caused the functions FACT, FACT1, and FACT2 to be compiled, 
redefined, and the compiled definitions also written on the file FACT, COM for 
subsequent loading. 

18.2 Compiler Questions 

The compiler uses the free variables lapflg, strf , svf Ig, lef il and Istf il 
which determines various modes of operation. These variables are set by the 
answers to the 'compset' questions. When any of the top level compiling 
functions are called, the function compset is called which asks a number of 
questions. Those that can be answered 'yes' or 'no 8 can be answered with YES, 
Y, or T for YES; and NO„ N, or NIL for NO. The questions are: 

1. LISTING? 

The answer to this question controls the generation of a listing. Possible 
answers are: 

1 Prints output of pass 1, the LAP macro code. 

2 Prints output of pass 2, the machine code. 
YES Prints output of both passes. 

NO Prints no listings. 

The variable lapf Ig is set to the answer. If the answer is affirmative, 
compset will type FILE: to allow the user to indicate where the output is to be 
written. The variable Istfil is set to the answer. 



The LAP and machine code are usually not of interest but can be helpful in 
debugging macros. 
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There are three other possible answers to LISTING? - each of which specifies a 
complete mode for compiling. They are: 

S Same as last setting. 

F Compile to File (no definition of functions). 

ST STore new definitions. 

STF STore new definitions. Forget exprs. 

Implicit in these three are the answers to the questions on disposition of 
compiled code and expr's, so questions 2 and 3 would not be asked if 1 were 
answered with S, F, ST P or STF. 

2. REDEFINE? 

YES Causes each function to be redefined as it is compiled. The 
compiled code is stored and the function definition changed. 
The variable strf is set to T, 

NO Causes function definitions to remain unchanged. The variable 
strf is set to NIL. 

The answer ST or STF for the first question implies YES for this question, F 
implies NO, and S makes no change. 

3. SAVE EXPRS? 

If answered YES, svf Ig is set to T, and the exprs are saved on the property 
list of the function name. Otherwise they are discarded. The answer ST for 
the first question implies YES for this question, F or STF implies NO, and S 
makes no change. 
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4. OUTPUT FILE: 



If the compiled definitions are to be written for later loading, you should 
provide the name of a file on which you wish to save the code that is 
generated. If you answer T or TTY:, the output will be typed on the teletype 
(not particularly useful). If you answer N, NO, or NIL, output will not bo 
done. If the file named is already open, it will continue to be used. The 
free variable lef il is set to the name of the file. 

18.3 Nlambdas 

When compiling the call to a function, the compiler must prepare the arguments 
to the function in one of three ways: 

1. Evaluated (SUBR, SUBR*, EXPR, EXPR*, CEXPR, CEXPR*) 

2. Unevaluated, spread (FSUBR, FEXPR, CFEXPR) 

3. Unevaluated, not spread (FSUBR*, FEXPR*, CFEXPR*) 

in attempting to determine which of these three is appropriate, the compiler 
will first look for a definition among the functions in the file that is being 
compiled. If the function is not contained there, the compiler will look, for 
other information which can be supplied by the user by including n lambda 
nospread functions on the list nlama (for n lam bda atoms), and including nlambda 
spread functions on the list nlaml (for nlam bda list), and including lambda 
functions on the list lams. * If the function is not contained in the file, 5 or 



Including functions on lams is only necessary to override in-core nlambda 
definitions, since in the absence of other information, the compiler 
assumes the function is a lambda. 

The function can be defined anywhere in any of the files given as arguments 
to bcompl , tcompl , brecompile or recompile . 
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on the list nlama, nlaml , or lams , the compiler will look for a current 
definition. If the function is defined, its function type is assumed to be the 
desired type. If it is not defined, the compiler assumes that the function is 
of type 1, i.e. its arguments are to be evaluated. In other words, if there 
are type 2 or 3 functions called from the functions being compiled, and they 
are only defined in a separate file, they must be included on nlama or nlaml » 
or the compiler will incorrectly assume that their arguments are to be 
evaluated, and compile the calling function correspondingly. Note that this is 
only necessary if the compiler does not 'know 1 about the function. If tho 
function is defined at compile time, or is handled via a macro, or is contained 
in the same group of files as the functions that call it, the compiler will 
automatically handle calls to that function correctly. 



18.4 Global Variables 



Variables that appear on the list globalvars or have the property GLOBALVAR, 
with value T, are called global variables. Such variables are always accessed 
through their value cell when they are used freely in a compiled funtion . In 
other words, a reference to the value of this variable is equivalent to 
(CAR (QUOTE variable) ), regardless of whether or not it appears on the stack, 



Before making this assumption, if the value of compileuserf n is not NIL. 
the compiler calls (the value of) compileuserf n giving it as arguments cdr 
of the form and the form itself, i.e. the compiler does 
(APPLY* COMPILEUSERFN (CDR form) form). If a non-NIL value is returned, it 
is compiled instead of form. If MIL is returned, the compiler compiles tho 
original expression as a call to a lambda-spread that is not yet defined. 
CLISP (Section 23) uses compileuserf n to tell the compiler how to compile 
iterative statements, IF-THEN-ELSE statements, and pattern match 
constructs. 



The names of functions so treated are added to the list a lams 
(for assumed lamdas) . a lams is not used by the compiler; it is maintained 
for the user's benefit, i.e. so that the user can check to see whether any 
incorrect assumptions were made. 
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i.e., the stack is not even searched for this variable when the compiled 
function is entered. Similarly, (SETQ variable value) is equivalent to 
(RPLACA (QUOTE variable) value); i.e., it sets the top-level value. 

All system parameters, unless otherwise specified, are global variables, i.e. 
have on their property lists the property GLOBALVAR with value T, e.g. 
brokenf ns , editmacros , #rpars , dwimf Ig , et al. Thus, rebindtng these variables 
will not affect the behavior of the system: instead, the variables must be 
reset to their new values, and if they are to be restored to their original 
values, reset again. For example, the user might write 
...(SETQ globalvar new-value) form (SETQ globalvar old-value). Note that in 
this case, if an error occurred during the evaluation of form , or a control-D 
was typed, the global variable would not be restored to its original value. 
The function resetvar (described in Section 5) provides a convenient way of 
resetting global variables in such a way that their values are restored even if 
an error occurred or control-D is typed. 

18.5 Compiler Functions 

Mote: when a function is compiled from its in core definition, i.e., via 
compile , recompile , or brecompile , as opposed to tcompl or bcompl (which uses 
the definitions on a file), and the function has been modified by break , trace , 
breakin , or advise , it is first restored to its original state, and a message 
printed out, e.g., F00 UNBROKEN. If the function is not defined as an expr, its 
property list is searched for the property EXPR (see savedef , section 8). If 



Since the stack does not have to be searched to find the values of these 
variables, a considerable savings in time is achieved, especially for deep 
computations. 
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there is a property EXPR, its value is used for the compilation- If there is no 
EXPR and the compilation is being performed by recompile or brecompilo , the 
definition of the function is obtained from the file (using loadfns ) . 
Otherwise, the compiler prints (fn NOT COMPILEABLE) , and goes on to the next 
function . 

compile[x;f Ig] x is a list of functions (if atomic, list[x] is 

used), compile first asks the standard compiler 
questions, and then compiles each function on x, 
using its in-core definition. Value is x. 

If compiled definitions are being dumped to a 
file, the file is closed unless flcpT. 

compile 1[ name ;def] compiles def, redefining name if &lrf~l. 9 compilel 

is used by compile , tcompl , and recompile . If 
dwimifycompf Ig is T, or def contains- a CLISP 
declaration, def is dwimified before compiling. 
See Section 23. 

tcompl[files] tcompl is used to Compile files 9 , i.e., given a 

symbolic load file (e.g., one created by 
prettydef ) , it produces a 'compiled file 1 that 
contains the same S~expressions as the original 
symbolic file, except that (1) a special 
FILECREATEO expression appears at the front of the 
file which contains information used by the file 
package, and which causes the message COMPILED 



strf is one of the variables set by compset, described earlier. 
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OH followed by the date, to be printed whon tho 
file is loaded; (2) every def ineq in the symbolic 
file is replaced by the corresponding compiled 
definitions in the compiled file;** and (3) 
expressions of the form (DECLARE: — DONTCOPY 
that appear in the symbolic file are not copied to 
the compiled file. This 'compiled 1 file can be 
loaded into any XNTERLISP system with load . 



fj les is a list of symbolic files to be compiled 
(if atomic, I1st[f1les] is used), tcompl asks the 
standard compiler questions, except for 
OUTPUT FILE: instead, the output from the 
compilation of each symbolic file is written on a 
file of the same nam© suffixed with C0M P i2 e.g., 
tcompl[(SYMl SYM2 ) ] produces two files 9 SYM1.COM 
and' SYM2.COM. 13 

tcompl processes each file one at a time, reading 



10 



11 



The actual string printed is the value of compileheader , initially 
"COMPILED ON". The user can reset compileheader , for example to 
distinguish between files compiled by different systems. 

The compiled definitions appear at the front of the compiled file, i.e. 
before the other expressions in the symbolic file, regardless of where they 
appear in the symbolic file. 



The actual suffix used is the value of the variable compile.ext , which is 
initially COM. The user can reset compile .ext or rename the compiled file 
after it has been written, without adversely affecting any of the system 
packages . 



The file name is constructed from the name field only, e.g. 
tcompl[ <B0BR0W>F00.TEM;3] produces F00.COM on the connected directory. The 
version number will be the standard default. 
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in the entire file. For each FILECREATED 
expression, the list of functions that were marked 
as changed by the file package (see section 14) is 
noted, 14 and the FILECREATED expression is written 
onto the output file. For each DEFINEQ expression, 
tcompl adds any NLAMBDA 1 s in the DEFINEQ to nlarna 
or laml , i6 and adds LAMBDA'S to the list lams > 16 
so that calls to these functions will be compiled 
correctly. Expressions beginning with DECLARE: 
are processed specially as described below. All 
other expressions are collected to be subsequently 
written onto the output file. After processing the 
file in this fashion, tcompl compiles each 
funtion, and writes the compiled definition onto 
the output file. tcompl then writes onto the 
output file the other expressions found in the 
symbolic file. 

The value of tcompl is a list of the names of the 



14 

15 
16 



17 



for use by recompile and brecompile which use the same low level funtions 
as tcompl and bcompl . 

described earlier, page 18.5. 

nlama , nlaml , and lams are rebound to their top level values (using 
resetvar ) by tcompl , recompile , bcompl , brecompile , compile , and 
blockcompile , so that any additions to these lists while inside of those 
functions will not propagate outside. 

except for those functions which appear on the list dontcom p ilefns » 
initially NIL. For example, this option might be used for functions that 
compile open, since their definitions would be superfluous when operating 
with the compiled file. Note that dontcompilefns can be set via block 
declarations page 18.30. 
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output files. All files are properly terminated 
and closed. If the compilation of any file is 
aborted via an error or control-D, all files are 
properly closed, and the (partially complete) 
compiled file is deleted. 

DECLARE: 

For the purposes of compilation, DECLARE: (see section 14) has two principal 
applications: (1) to specify forms that are to be evaluated at compile time, 
presumably to affect the compilation, e.g. to set up macros; and/or (2) to 
indicate which expressions appearing in the symbolic file are noi to be copied 
to the output file. (Normally, expressions are not evaluated and are copied.) 
Each expression in cdr of a DECLARE: form is either evaluated/not -evaluated and 
copied/not-copied depending on the settings of two internal state variables, 
initially set for copy and not-evaluate . These state variables can be reset 
for the remainder of the expressions in the DECLARE: by means of the ■ tags 
DOEVAL0COMPILE (or EVAL8C0MPILE ) and DONTCOPY, e.g. 

(DECLARE: DOEVAL0COMPILE DONTCOPY (DEFLIST (QUOTE MACRO))) could be used to 
set up macros at compile time. 

Recompile 

The purpose of recompile is to allow the user to update a compiled file without 
recompiling every function in the file. Recompile does this by using the 
results of a previous compilation. It produces a compiled file similar to one 
that would have been produced by tcompl , but at a considerable savings in time 
by compiling selected functions and copying from an earlier tcompl or recompile 
file the compiled definitions for the remainder of the functions in the file. 
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recompile[pf ile ;cf ile;fns] pfile is the name of the pretty file to bo 

compiled, cf lie is the name of the compiled f ilo 
containing compiled definitions that may bo 
copied, fns indicates which functions in pf ilo 
are to be recompiled, e.g., have been changed or 
defined for the first time since cf ile was made. 
Mote that pfile , not fns , drives recompile . 



recompile asks the standard compiler questions, 

except for OUTPUT FILE:. As with tcompl , the 

output automatically goes to pfile. COM . 18 19 

recompile process pfile the same as does tcompl 

except that DEFINEQ expressions are not actually 

read into core. Instead, recompile uses the 

on 

filemap (see section 14) to obtain a list of the 
functions contained in pfile , and simply skips 
over the DEFINEQ' $. 21 

After this initial scan of pfile , recompile then 



18 



19 



20 



21 



or pfile. ext, where ext is the value of compile. ext . 

In general, all constructions of the form pfile.COH, pfileCOMS, 
pfileBLOCKS, etc., are performed using the name field only. For example, 
if pf ile =<BOBROW>FOO . TEM ; 3 , pfile.COM means F00.COM, pfileCOMS means 
FOOCOMS, etc. 

A map is built if the symbolic file does not already contain one, e.g. it 
was written in an earlier system, or with buildmapf Ig sNIL. 

The filemap enables recompile to skip over the DEFINEQ' s in the file by 
simply resetting the file pointer, so that in most cases the scan of the 
symbolic file is very fast (the only processing required is the reading of 
the non-DEFINEQ's and the processing of the DECLARE: expressions as 
described earlier). 
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processes the functions defined in the file. For 
each function in pf ile , recompile determines 
whether or not the function is to be ( re )compiled . 
A function is to be recompiled" if (1) fns is a 
list and the function is a member of that list; or 

(2) fns=T or EXPRS and the function is an expr; or 

(3) fnssCHANGES and the function is marked as 
having been changed in the FILECREATED expression; 
or (4) fnssALL. 23 If a function is not to be 
recompiled, recompile obtains its compiled 
definition from cf ile 9 and copies it (and all 
generated subfunctions) to the output file, 
pf ile.COM . 24 Finally, after processing all 
functions, recompile writes out all other 
expressions that were collected in the prescan of 
pfile . 

If cf ile sNIl. pfile.COM is used for copying 
from. 25 If both fns and cf lie are NIL, fns is 



22 
23 



24 



25 



Functions that are members of dontcompilefns are simply ignored. 

In this latter case, cf ile is superfluous, and in fact does not have to 
exist. This option is useful, for example, to compile a symbolic file that 
has never been compiled before, but which has already been loaded (since 
using tcompl would require reading the file in a second time). 

If the function does not appear on cf ile , an fn NOT FOUND error is 
generated, and recompile aborts. 

In other words, if cf ile , the file used for obtaining compiled definitions 
to be copied, is NIL, pfile.COM is used, i.e., same name as output file but 
a different version number (one less) than the output file. 
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set to T 9 meaning recompile all exprs. 



The value of recompile is the new compiled file, 
pfile.COM . If recompile is aborted due to an 
error or control-D, the new (partially complete) 
compiled file will be closed and deleted. 

recompile is designed to allow the user to conveniently and efficiently update 
a compiled file, even when the corresponding symbolic file has not been 
(completely) loaded, for example, the user can perform a loadf rom (section 14) 
to 'notice' a symbolic file, and then simply edit the functions he wanted to 
change, 25 call makefile , 2 ^ and then perform recompile[pf ile]. 5 ^ 

18.6 Open Functions 

When a function is called from a compiled function*, a system routine is invoked 



This is the most common useage. Typically, the functions the user has 
changed will have been unsavedef ed by the editor, and therefore will be 
exprs. Thus the user can perform his edits, dump the file,; and then simply 
recompile[ f ile] to update the compiled file. 
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28 



29 



30 



The loadfrom would be unnecessary if the compiled file had been previously 
loaded, since this would also result in the file having been 'noticed*. 

As described in section 9„ the editor would automatically load those 
functions not already loaded. 

As described in section 14, makefile would copy the unchanged functions 
from the symbolic file. 

Since prettydef automatically outputs a suitable DECLARE: expression to 
indicate which functions in the file (if any) are defined as NLAMBDA ' s , 
calls to these functions will be handled correctly, even though the NLAMBDA 
functions themselves may never be loaded, or even looked at, by recompile . 
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that sets up the parameter and control push lists as necessary for variable 
bindings and return information. As a result, function calls can take up to 
350 microseconds per call. If the amount of time spent inside the function is 
small, this function calling time will be a significant percentage of the total 
time required to use the function. Therefore, many 'small 1 functions, e.g., 
car , cdr , eg , not , cons are always compiled 'open 1 , i.e., they do not result in 
a function call. Other larger functions such as prog , selectq , mapc , etc. are 
compiled open because they are frequently used. It is useful to know exactly 
which functions are compiled open in order to determine where a program is 
spending its time. Therefore below is a list of those functions which when 
compiled do not result in function calls. Note that the next section tells how 
the user can make other functions compile open via MACRO definitions. 

The following functions compile open in INTERLISP- 10 : 

AC, ADD1, AND, APPLY* , ARG. ARRAYP, ASSEMBLE, ATOM, BLKAPPLY, BLKAPPLY«, CAR, 
COR, CAAR, ... CDDDAR, C0DD0R, CLOSER, COND, CONS, EQ, ERSETQ, EVERY, EVQ, 
FASSOC, FCHARACTER, FDIFFERENCE , F6TP, FIX, FIXP, FLAST, FLENGTH, FLOAT, 
FLOATP , FMEMB, FMINUS, FNTH, FPLUS, FQUOTIENT, FRPLACA, FRPLACD, F5TKARG, 
FSTKNTH, FTIMES, FUNCTION, GETHASH, GO, IDIFFERENCE, IGREATERP, ILESSP, IMINUS, 
IPLUS. I0UOTIENT. IREMAINDER, ITIMES, LIST, LISTP. LITATOM, LLSH. LOC , LOGAND, 
LOGOR, LOGXOR, LRSH , LSH, MAP, MAPC, MAPCAR, MAPCON, MAPCONC , MAPLIST. MINUSP, 
NEQ, NLISTP, NLSETQ. NOT, NOTEVERY, NOTANY, NTYP, NULL, NUMBERP, OPENR, OR, 
PROG, PROG1, PROGN, RESETFORM, RESETLST, RESETSAVE, RESETVAR, RETURN, RPTQ, 
RSH, SELECTQ, SETARG, SETN, SETQ, SMALLP, SOME, STRINGP, SUB1, SUBSET, TYPEP. 
UNDONLSETQ, VAG, ZEROP 



The user can also affect the compiled code via complleuserfn , described in 
footnote on page i8.6. 
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18.7 Compiler Macros 



The IMTERLISP compiler includes a macro capability by which the user can affect 
the compiled code. Macros are defined by placing the macro definition on tho 
property list of the corresponding function, under the property MACRO. — When 
the compiler begins compiling a form, it retrieves a macro definition for car 
of the form, if any, and uses it to. direct the compilation* The three 
different types of macro definitions are given below. 

(1) Open macros - ( LAMBDA ...) or (NLAMBDA ...) 

A function can be made to compile open by giving it a macro definition of the 
form (LAMBDA ...) or (NLAMBDA ...), e.g., 

(LAMBDA (X) (COND ((GREATERP X 0) X) (T (MINUS X)))) for abs. The effect is 
the same as though the macro definition were written in place of the function 
wherever it appears in a function being compiled, i.e., it compiles as an open 
LAMBDA or NLAMBDA expression. This saves the time necessary to call the 
function at the price of more compiled code generated. 

(2) Computed macros - (atom expression) 

A macro definition beginning with an atom other than LAMBDA, NLAMBDA, or NIL, 
allows computation of the IMTERLISP expression that is to be compiled in place 
of the form. The atom which starts the macro definition is bound to cdr of the 



An expression of the form (DECLARE (DEFLIST ... (QUOTE MACRO))) can be used 
within a function to define a MACRO. DECLARE is defined the same as QUOTE 
and thus can be placed so as to have no effect on the running of the 
function . 



The compiler has built into it how to compile certain basic functions such 
as car , prog , etc., so that these will not be affected by macro 
definitions. These functions are listed above. However, some of them are 
themselves implemented via macros, so that the user could change the way 
they compile. 
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form being compiled. The expression following the atom is then evaluated, and 
the result of this evaluation is compiled in place of the form. For example, 
list could be compiled this way by giving it the macro definition: 

[X (LIST (QUOTE CONS) 
(CAR X) 
(AND (CDR X) 

(CONS (QUOTE LIST) 
(CDR X] 



This would cause (LIST X Y Z) to compile as (CONS X (CONS Y (CONS Z NIL))) 
Note the recursion in the macro expansion, 35 Ersetq , nlsetq , map , mapc „ mapcar 
mapconc , and some , are compiled via macro definitions of this type. 



(3) Substitution macro - (NIL expression) or (list expression) 

Each argument in the form being compiled is substituted for the corresponding 
atom in car of the macro definition, and the result of the substitution is 
compiled instead of the form, i.e., 

(SUBPAIR (CAR macrodef) (CDR form) (CADR macrodef)). For example, the macro 
definition of addl is ((X) (IPLUS X 1)). Thus, (ADD1 (CAR Y) ) is compiled as 
(IPLUS (CAR Y) 1). The functions addl, sub'l , neq , nlistp, zerop , f length , 
fmenb, f assoc , f last , and fnth are all compiled open using substitution macros. 
Note that abs could be compiled open as shown earlier or via a substitution 
macro. A substitution macro, however, would cause (ABS (F00 X)) to compile as 
(COND ( ( GREATER? (FOO X) 0) (FOO X) ) (T (MINUS (FOO X)))) and consequently 
(FOO X) would be evaluated three times. 



In INTERLISP-10, if the result of the evaluation is the atom INSTRUCTIONS, 
no code will be generated by the compiler. It is then assumed the 
evaluation was done for effect and the necessary code, if any, has been 
added. This is a way of giving direct instructions to the compiler if you 
understand it . 

list is actually compiled more efficiently. 
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18.8 FUNCTION and Functional Arguments 



Expressions that begin with FUNCTION will always be compiled as separate 
functions 5 ^ named by attaching a gensym to the end of the name of the function 
in which they appear, e.g., FOOA0003. This gensym function will be called at 
run time. Thus if F00 is defined as 

(LAMBDA (X) .... (FOOl X (FUNCTION ...)) ...) and compiled, then when F00 is 
run, FOOl will be called with two arguments, X, and FOOA000n, 5S and then FOOl 
will call FOOAOOOn each time it must use its functional argument. 



Note that a considerable savings in time could be achieved by defining FOOl as 
a computed macro of the form: 

(Z (LIST (SUBST (CADADR 2) (QUOTE FN) def) (CAR Z))) 

where def is the definition of FOOl as a function of just its first argument 
and FN is the name used for its functional argument in its definition. The 
expression compiled contains what was previously the functional argument to 
FOOl, as an open LAMBDA expression. Thus you save not only the function call 
to FOOl , but also each of the function calls to its functional argument. For 
example, if FOOl operates on a list of length ten, eleven function calls will 
be saved. Of course, this savings in time cost space, and the user must decide 
which is more important. 
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except when they are compiled open, as is the case with most of the mapping 
functions. 

nlsetq and ersetq expressions also compile using gensym functions. As a 
result, a go or return cannot be used inside of a compiled nlsetq or ersetq 
if the corresponding prog is outside, i.e. above the nlsetq or ersetq . 

or an appropriate funarg expression, see Section 11. 
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18,9 Block Compiling 



Block compiling provides a way of compiling several functions into a single 
block. Function calls between the component functions of the block are very 
fast, and the price of using a free variable, namely the time required to look 
up its value on the stack, is paid only once - when the block is entered. 
Thus, compiling a block consisting of just a single recursive function may be 
yield great savings if the function calls itself many times, e.g., equal , copy , 
and, count are block compiled in INTERLISP . 

The output of a block compilation is a single, usually large, function. This 
function looks like any other compiled function; it can be broken, advised, 
printstructured, etc. Calls from within the block to functions outside of tho 
block look like regular function calls, except that they are usually linked 
(described below). A block can be entered via several different functions, 

on 

called entries. These must be specified when the block is compiled. For 
example, the error block has three entries, errorx » interrupt , and fault! . 
Similarly, the compiler block has nine entries. 

Specvars 

One savings in block compiled functions results from not having to store on the 
stack the names of the variables bound within the block, since the block 
functions all 'know 1 where the variables are stored. However, if a variable 
bound in a block is to be referenced outside the block, it must be included on 



Actually the block is entered the same as every other function, i.e., at 
the top. However, the entry functions call the main block with their name 
as one of its arguments, and the block dispatches on the name, and jumps to 
the portion of the block corresponding to that entry point. The effect is 
thus the same as though there were several different entry points. 
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the list specvars . For example, helpclock is on specvars , since it is rebound 
inside of lispxblock and editblock, but the error functions must be able to 
obtain its latest value. 

Localf reevars 

Localf reevars is a feature designed for those variables which are used freely 
by one or more of the block functions, but which are always bound (by some 
other block function) before they are referenced, i.e. their free values above 
the block are never used. Normally, when a block is entered, all variables 
which are used freely by any function in the block are looked up and pointers 
to the bindings are stored on the stack* . When any of these variables are 
rebound in the block, the old pointer is saved and a pointer to the new binding 
is stored in the original stack position. It frequently happens that variables 
used freely within a block are in fact always bound within the block prior to 
the free reference. The unnecessary lookup of the value of the free variable 
at the time of entry to the block can be avoided by putting the variable name 
on the list localf reevars . If a variable is on localf reevars , its value will 
not be looked up at the time of entry. When the variable is bound, the value 
will be stored in the proper stack position. Should the variable in fact be 
referenced before it is bound, the program will still work correctly. 
Invisible to the user, a rather time-consuming process will take place. The 
reference will cause a trap which will invoke code to determine which variable 
was referenced and look up the value. Future references to that variable 
during this call to the block will be normal, i.e. will not cause a trap. 



Arguments to the block that are referenced freely outside the block must 
also be SPECVARS if they are reset within the block, or else the new value 
will not be obtained. 
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trapcount[x] is a function to monitor the performance of block 

compiled code with respect to localf reevars . If x 
is NIL, trapcount returns the cumulative number of 
traps caused by localf reevars that were not bound 
before use. If x is a number, the trapcount is 
reset to that number, 

evq is another compiler artifice for free variables references. (EVQ X) has 
the effect of (EVAL (QUOTE X)) without the call to eval (if X is an atom), evq 
is intended primarily for use in conjunction with localf reevars . For example, 
suppose a block consists of three functions, FOOl, F002, and F003, with FOOl 
and F002 being entries, and F003 using X freely, where X is bound in FOOl, but 
not in F002, i.e. FOOl rebinds X, but when entered via F002, the user intends X 
to be used freely, and its higher value obtained. If X is on localf reevars » 
then each time the block is entered via F002, a trap will occur when F003 first 
references X. In order to avoid this, the user can insert (EVQ X) in F002 . 
This will circumvent the trap by explicitly invoking the routine that searches 
back up the stack for the last binding of X. Thus, when used with 
localf reevars , evq does two things: it returns the value of its argument, and 
also stores that value in the binding slot for the variable so that no future 
references to that variable (in this call) will cause traps. Since the time 
consumed by the trap can greatly exceed the time required for a variable 
lookup, using evq in these situations can result in a considerable savings, 

Retfns 

Another savings in block compilation arises from omitting most of the 
information on the stack about internal calls between functions in the block. 
However, if a function's name must be visible on the stack, e.g., if the 
function is to be returned from retfrom , it must be included on the list 
retfns . 
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Blkapplyf ns 



Normally, a call to apply from inside a block would be the same as a call to 
any other function outside of the block. If the first argument to apply turned 
out to be one of the entries to the block, the block would have to be 
reentered, blkapplyfns enables a program to compute the name of a function in 
the block to be called next, without the overhead of leaving the block and 
reentering it. This is done by including on the list blkapplyfns those 
functions which will be called in this fashion, and by using blkapply in place 
of apply , and blkapply** in place of apply* . For example, the calls to the 
functions handling RI, RO, LI, L0 9 BI, and BO in the editor are handled this 
way. If blkapply or blkapply* is given a function not on blkapplyfns , the 
effect is the same as a call to apply or apply* and no error is generated. 
Note however, that blkapplyfns must be set at compile time, not run time, and 
furthermore, that all functions on blkapplyfns must be in the block, or an 
error is generated (at compile time), NOT ON BLKFNS. 

Blklibrary 

Compiling a function open via a macro provides a way of eliminating a function 
call. For block compiling, the same effect can be achieved by including the 
function in the block. A further advantage is that the code for this function 
will appear only once in the block, whereas when a function is compiled open, 
its code appears at each place where it is called. 

The block library feature provides a convenient way of including functions in a 
block. It is just a convenience since the user can always achieve the same 
effect by specifying the function(s) in question as one of the block functions, 
provided it has an expr definition at compile time. The block library feature 
simply eliminates the burden of supplying this definition. 
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To use the block library feature, place the names of the functions of interest 
on the list blklibrary , and their EXPR definition on the property list of the 
function under the property BLKLIBRARYDEF . When the block compiler compiles a 
form, it first check to see if the function being called is one of the block 
functions. If not, and the function is on blklibrary , its definition is 
obtained from the property value . of BLKLIBRARYDEF, and it is automatically 
included as part of the block. The functions assoc , equal , getp , last , length , 
lispxwatch , memb , nconcl , nleft, nth , and /rplnode already have BLKLIBRARYDEF 
properties. 

18.10 Linked Function Calls 

Conventional (non-linked) function calls from a compiled function go through 
the function definition cell, i.e., the definition of the called function is 
obtained from its function definition cell at call time. Thus, when the user 
breaks, advises, or otherwise modifies the definition of the function FOO, 
every function that subsequently calls it instead calls the modified function. 
For calls from the system functions, this is clearly not a feature. For 
example, the user may wish to break on basic functions such as print , oval , 
rplaca , etc., which are used by the break package. In other words, we would 
like to guarantee that the system packages will survive through user 
modification (or destruction) of basic functions (unless the user specifically 
requests that the system packages also be modified). This protection is 
achieved by linked function calls. 

For linked function calls, the definition of the called function is obtained at 
link time, i.e., when the calling function is defined, and stored in the 
literal table of the calling function. At call time, this definition is 
retrieved from where it was stored in the literal table, not from the function 
definition cell of the called function as it is for non-linked calls. These 
two different types of calls are illustrated in Figure 18-1. 
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Note that while function calls from block compiled functions are usually 
linked, and those from standardly compiled functions are usual ly non-linked, 
linking function calls and blockcompiling are independent features of the 
IMTERLISP compiler, i.e., linked function calls are possible, and frequently 
employed, from standardly compiled functions. 
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Mote that normal function calls require only the called function's name in the 
literals of the compiled code, whereas a linked function call uses two literals 
and hence produces slightly larger compiled functions. 



The compiler's decision as to whether to link a particular function call is 
determined by the variables linkfns and nolinkfns as follows: 

(1) If the function appears on nolinkfns , the call is not linked; 

(2) If block compiling and the function is one of the block functions, the 
call is internal as described earlier; 

(3) If the function appears on linkfns , the call is linked; 

(4) If nolinkfns sT, the call is not linked; 

(5) If block compiling, the call is linked; 

(6) If linkfnssT, the call is linked; 

(7) Otherwise the call is not linked. 

Note that ( 1 ) takes precedence over (2), i.e., if a function appears on 
nolinkfns , the call to it is not linked, even if it is one of the functions in 
the block, i.e., the call will go outside of the block. 

Nolinkfns is initialized to various system functions such as errorset , breakl , 
etc. Linkfns is initialized to NIL. Thus if the user does not specify 
otherwise, all calls from a block compiled function (except for those to 
functions on nolinkfns ) will be linked; all calls from standardly compiled 
functions will not be linked. However, when compiling system functions such as 
help , error , arglist , fntyp , breakl , et al, linkfns is set to T so that even 
though these functions are not block compiled, all of their calls will be 
linked. 

If a function is not defined at link time, i.e., when an attempt is made to 
link to it, it is linked instead to trie function nolinkdef . When the function 
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is later defined, the link can be completed by relinking the calling function 
using relink described below. Otherwise, if a function is run which attempts a 
linked call that was not completed, nollnkdef is called. If the function is 
now defined, i.e., it was defined at some point after the attempt was made to 
link to it, nolinkdef will quietly perform the link and continue the call. 
Otherwise, it will call faultapply and proceed as described in Section 10. 

Linked function calls are printed on the backtrace as ;fn; where fn is the name 
of the function. Note that this name does not actually appear on the stack, 
and that stkpos , retfrom , and the rest of the pushdown list functions (Section 
12) will not be able to find it. Functions which must be visible on the stack 
should not be linked to, i.e., include them on nolinkfns when compiling a 
function that would otherwise link its calls. 

printstructure , calls , break on fnl*»IN-fn2 and advise fnl-IN-fn2 all work 
correctly for linked function calls, e.g., break[(FOO IU FIE)], where FOO is 
called from FIE via a linked function call. 

Relinking 

The function relink is available for relinking a compiled function, i.e., 
updating all of its linked calls so that they use the definition extant at the 
time of the relink operation. 

relink[fn] fn is either WORLD, the name of a function, a list 

of functions, or an atom whose value is a list of 
functions. relink performs the corresponding 
relinking operations. relink[ WORLD] is possible 
because laprd maintains on linkedfns a list of all 
user functions containing any linked calls. 
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syslinkedfns is a list of all system functions 
that have any linked calls. relink[ WORLD] 
performs both relink[ linkedfns] and 

relink[ syslinkedfns]. 

The value of relink is fn. 

It is important to stress that linking takes place when a function is defined. 
Thus, if F00 calls FIE via a linked call, and a bug is found in FIE, changing 
FIE is not sufficient; F00 must be relinked. Similarly, if F001, F002, and 
F003 are defined (in that order) in a file, and each call the others via linked 
calls, when a new version of the file is loaded, F001 will be linked to the old 
FOOZ and F003, since those definitions will be extant at the time it is road 
and defined. Similarly, F002 will link to the new F001 and old F003. Only 
F003 will link to the new F001 and F002. The user would have to perform 
relink[FOOFNS] following the load . 

18.11 The Block Compiler 

There are three user level functions for blockcompiling, blockcompile , bcompl , 
and brecompile , corresponding to compile , tcompl, and recompile . All of them 
ultimately call the same low level functions in the compiler, i.e., there is no 
'blockcompiler 1 per se. Instead, when blockcompiling, a flag is set to enable 
special treatment for specvars , retfns , blkapplyfns , and for determining 
whether or not to link a function call. Note that all of the previous remarks 
on macros, globalvars, compiler messages, etc., all apply equally for block 
compiling. Using block declarations described below, the user can intermix in 
a single file functions compiled normally, functions compiled normally with 
linked calls, and block compiled functions. 
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Blockcompile 



blockcompile[blkname;blkfns$entries;f Ig] blkfns is a list of the functions 

comprising the block, blkname is tho name of the 
block, entries a list of entries to the block, 
e.g., 

-BLOCKCOMPILE(SUBPRBLOCK (SUBPAIR SUBLIS SUBPR) (SUBPAIR SUBLIS)) 

Each of the entries must also be on blkfns or an 
error is generated, NOT ON BLKFNS.^ 1 

If entries is NIL, list[blkname] is used, e.g., 
«-BL0CKC0MPILE( COUNT (COUNT COUNT1)) 

If blkfns is NIL, list[blkname] is used, e.g., 
*BL0CKC0MPILE(EQUAL) 

blockcompile asks the standard compiler questions 
and then begins compiling. As with compile , if 
the compiled code is being written to a file, the 
file is closed unless f lg =T . The value of 
blockcompile is a list of the entries, or if 
entries sNIL, the value is blkname . 

The output of a call to blockcompile is one 



^ If only one entry is specified, the block name can also be one of the 
blkfns , e.g. BL0CKC0MPILE(F00 (FOO FIE FUM) (F00)). However, if more than 
one entry is specified, an error will be generated, 
CAN'T BE BOTH AN ENTRY AND THE BLOCK NAME. 
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function definition for blkname, plus definitions 
for each of the functions on entries if any. 
These entry functions are very short functions 
which immediately call blkname . 

Block Declarations 

Since block compiling a file frequently involves giving the compiler a lot of 
information about the nature and structure of the compilation, e.g., block 
functions, entries, specvars, linking, et al, we have implemented a special 
prettydef command to facilitate this commmunication . The user includes in the 
third argument to prettydef a command of the form 

(BLOCKS blockj ... block^ ... block n ) where each blockj is a block declaration. 
bcompl and brecompile described below are sensitive to these declarations and 
take the appropriate action. 

The form of a block declaration is: 

(blkname blkfn 1 ... blkfn m (var^ . value) ... (var n .value)) 

blkfn^ ... blkfn m are the functions in the block and correspond to blkfns in 
the call to blockcompile * The (var . value) expressions indicate the settings 
for variables affecting the compilation, 

As an example, the value of editblocks is shown below. It consists of three 
block declarations, editblock , editf indblock , and edit4e . 
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[RPAQQ EDITBLOCKS 

( ( EDITBLOCK EDITLO EDITL1 UNDOEDITL EDITCOM E0ITCOMA EDITCOML 
EDITMAC EDITCOMS EDIT]UNDO UNDOEDITCOM 
UNDOEDITCOM1 EDITSMASH EDITNCONC E0IT1F EDIT2F 
EDITMTH BPNT BPHTO BPHT1 RI RO LI LO BI BO 
EDITDEFAULT EDUP EDIT" EDOR EDRPT EDLOC EDLOCL 
EDIT: EDITMBD EOITXTR EOITELT EDITCONT EOITSW 
EDITMV EDITTO EOITBELOW EDITRAN TAILP EDITSAVE 
EDITH (ENTRIES EDITLO #f» UNDOEDITL) 
(SPECVARS L COM LCFLG #1 #2 #3 LISPXBUFS 

**COMMENT**FLG PRETTYFLG UNDOLST 

UNDOLST1) 
(RETFNS EDITLO) 

(GLOBALVARS EDITCOMSA EDITCOMSL EDITOPS 

HISTORYCOMS EDITRACEFN) 
(BLKAPPLYFNS RI RO LI LO BI BO EDIT: EDITMBD 

EDITMV EDITXTR) 
(BLKLIBRARY LENGTH NTH LAST) 
(NOLINKFNS EDITRACEFN)) 
(EDITFINDBLOCK EDIT4E EDIT4E1 EDITQF EDIT4F EDITFPAT 

EDITFPAT1 EDIT4F1 EDIT4F2 EDIT4F3 EDITSMASH 
EDITFINDP EDITBF EDITBF1 ESUBST 
(ENTRIES EDITQF EDIT4F EDITFPAT EDITFINDP 
EDITBF ESUBST)) 
(EDIT4EBL0CK EDIT4E EDIT4E1 (ENTRIES EDIT4E EDIT4E1 ] 



Whenever bcompl or brecompile encounter a block declaration*^ they rebind 
retfns . specvars , localfreevars, globalvars , blklibrary , nolinkfns , linkfns , 
and dontcompilefns to their top level value, bind blkappiyfns and entries to + 
NIL, and bind blkname to the first element of the declaration. They then scan 
the rest of the declaration, gathering up all atoms, and setting car of each 
nonatomic element to cdr of the expression if atomic, e.g., ( LINKFNS . T), or 
else to union of cdr of the expressions with the current (rebound) value, ^ 3 
e.g., (GLOBALVARS EDITCOMSA EDITCOMSL). When the declaration is exhausted, the 
block compiler is called and given blkname , the list of block functions, and 



The BLOCKS command outputs a DECLARE expression, which is noticed by bcompl 
and brecompile . ~ 



Expressions of the form (var "form) will cause form to be evaluated and 
the resulting list used as described above, e.g. 
(GLOBALVARS * MYGLOBALVARS) . 



18.31 



Note that since all compiler variables are rebound for each block declaration, 
the declaration only has to set those variables it wants changed. Furthermore, 
setting a variable in one declaration has no effect on the variable's value for 
another declaration. 

After finishing all blocks, bcompl and brecompile treat any functions in the 
file that did not appear in a block declaration in the same way as do tcompl 
and recompile . If the user wishes a function compiled separately as well as in 
a block, or if he wishes to compile some functions (not blockcompile) , with 
some compiler variables changed, he can use a special pseudo-block declaration 
of the form (NIL fn^ ... fn m (var| . value) ... (var n . value)) which means 
compile fn^ ... fn^ after first setting var^ ... var n as described above. For 
example, ( NIL CGETD FNTYP ARGLIST NARGS NC0NC1 GENSYM (LINKFNS T ) ) 
appearing as a 'block declaration* will cause the six indicated functions to be 
compiled while linkfns =T so that all of their calls will be linked (except for 
those functions on nolinkfns ). 

bcompl 

bcompl[f iles;cf ile] files is a list of symbolic files. (If atomic, 

list[files] is used.) bcompl differs from tcompl 
in that it compiles all of the files at once, 
instead of one at a time, in order to permit one 
block to contain functions in several files. 44 
Output is to cf ile if given, otherwise to a file 
whose name is car[ files] suffixed with COM,*' 6 



Thus if you have several files to be bcompled separately, you must make 
several calls to bcompl . 

or value of compile .ext, as explained earlier. 
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e.g., bcompl[(EDIT WEDIT)] produces one file, 
E0IT.COM. 



bcompl asks the standard compiler questions, 
except for OUTPUT FILE:, then processes each file 
exactly the same as does tcompl (see page 
18.10).^ Bcompl next processes the block 
declarations as described above. Finally, it 
compiles those functions not mentioned in one of 
the block declarations, and then writes out all 
other expressions. 

The value of bcompl is the output file (the new 
compiled file). If the compilation is aborted due 
to an error or control-D, all files are closed and 
the (partially complete) output file is deleted. 

Note that it is permissible to tcompl files set up 
for bcompl ; the block declarations will simply 
have no effect. Similarly, you can bcompl a file 
that does not contain any block declarations and 
the result will be the same as having tcompl ed it. 

Brecompile 



Brecompile plays the same role for bcompl that recompile plays for tcompl : 



In fact, tcompl is defined in terms of bcompl . The only difference is 
that tcompl calls bcompl with an extra argument specifying that all block 
declarations are to be ignored. 
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its purpose is to allow the user to update a compiled file without requiring on 
entire bcompl . 



brecompile[ f iles;cf ile;fns] files is a list of symbolic files (if atomic, 

list[ files] is used), cf lie is the compiled file 
corresponding to bcompl[files] or a previous 
brecompile , i.e. , it contains compiled definitions 
that may be copied. The interpretation of fns is 
the same as with recompile 

brecompile asks the standard compiler questions 
except for OUTPUT FILE: As with bcompl , output 
automatically goes to file.COM, where file is the 
first file in files. 

brecompile processes each file the same as does 
recompile as described on page 18.12, then 
processes each block declaration. If any of the 
functions in the block are to be recompiled, the 
entire block must be (is) recompiled. Otherwise, 
the block is copied from cf ile as with recompile . 
For pseudo-block declarations of the form 
(MIL fnl ...), all variable assignments are made, 
but only those functions so indicated by fns are 
recompiled. 

After completing the block declarations, 



In fact, recompile is defined in terms of brecompile . The only difference 
is that recompile calls brecompile with an extra argument specifying that 
all block declarations are to be ignored. 
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brecompile processes all functions that do not 
appear in a block declaration, recompiling those 
dictated by fns, and copying the compiled 
definitions of the remaining from cf ile . 

Finally, brecompile writes onto the output filo 
the 'other expressions 1 collected in the initial 
scan of files . 

The value of brecompile is the output file (the 
new compiled file). If the compilation is aborted 
due to an error or control-D, all files are closed 
and the (partially complete) output file is 
deleted. 

If cfiles NIL, file.COM is used. 45 In addition, if 
fns and cfile are both NIL, fns is set to T. 



18.12 Compiler Structure 

The compiler has two principal passes. The first compiles its input into a 
macro assembly language called LAP The second pass expands the LAP code, 
producing (numerical) machine language instructionsc The output of the second 
pass is written on a file and/or stored in binary program space. 
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See footnote on page 18.12. 

The exact form of the macro assembly language is extremely implementation 
dependent, as well as being influenced by the architecture and instruction 
set for the machine that will run the compiled program/ The remainder of 
section 18 discusses LAP for the INTERLISP-10 . 
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Input to the compiler is usually a standard INTERLISP S-expression function 
definition. However,, in INTERLISP- 10, machine language coding can be includod 
within a function by the use of one or more assemble forms. In other words, 
assemble allows the user to write protions of a function in LAP. Note that 
assemble is only a compiler directive; it has no independent definition. 
Therefore, functions which use assemble must be compiled in order to run. 

18.13 Assemble 



The format of assemble is similar to that of PROG: (ASSEMBLE V . . . S N ). 

V is a list of variables to be bound during the first pass of the compilation, 
not during the running of the object code. The assemble statements Sj . . . S N 
are compiled sequentially, each resulting in one or more instructions of object 
code. When run, the value of the assemble 'form 1 is the contents of AC1 at the 
end of the execution of the assemble instructions. Note that assemble may 
appear anywhere in an INTERLISP-10 function. For example, one may write: 

(IGREATERP (IQUOTIENT (LOC (ASSEMBLE NIL 

(MOVE I 1 , -5) 
(OSYS 13))) 

1000) 

4) 

to test if job runtime exceeds 4 seconds. 



Assemble Statements 

If an assemble statement is an atom, it is treated as a label identifying the 
location of the next statement that will be assembled. 60 Such labels defined in 



°^ A label can be the last thing in an assemble form, in which case it labels 
the location of the first instruction a/ter the assemble form. 
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an assemble form are like prog labels in that they may be referenced from the 
current and lower level nested progs or assembles . 

If an assemble statement is not an atom, car of the statement must be an atom 
and one of the following: (1) a number; (2) a LAP op-def (i.e. has a property 
value OPO); (3) an assembler macro (i.e. has a property value AMAC); or (4) one 
of the special assemble instructions given below, e.g. C, CQ, etc. Anything 
else will cause the error message OPCODE? - ASSEMBLE. 

The types of assemble statements are described here in the order of priority 
used in the assemble processor; that is, if an atom has both properties OPD and 
AMAC, the OPO will be used. Similarly a special assemble instruction may bo 
redefined via an AMAC. The following descriptions are of the first pass 
processing of assemble statements. The second pass processing is described in 
the section on LAP, page 18.41. 

(1) numbers - If car of an assemble statement is a number, the statement is not 

processed in the first pass. (See page 18.41.) 

(2) LAP op-defs - The property OPD is used for two different types of op-defs: 

PDP-1G machine instructions, and LAP macros. If the OPD 
definition (i.e. the property value) is a number, the op-def is a 
machine instruction. When a machine instruction, e.g. HRRZ , 
appears as car of an assemble statement, the statement is not 
processed during the first pass but is passed to LAP. The forms 
and processing of machine instructions by LAP are described on 
page 18.42. 

If the OPD definition is not a number, then the op-def is a LAP 
macro. When a LAP macro is encountered in an assemble statement, 
its arguments are evaluated and processing of the statement with 
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evaluated arguments is left for the second pass and LAP . For 
example, LDV is a LAP macro, and (LDV (QUOTE X) SP) in assemble 
code results in (LDV X H) in the LAP code, where N is the value 
of SP. 

The form and processing of LAP macros are described on page 
18.45. 

(3) assemble macros - If car of an assemble statement has a property AMAC , 
the statement is an assemble macro call. There are two types of 
assemble macros: lambda and substitution. If car of the macro 
definition is the atom LAMBDA, the definition will be applied to 
the arguments of the call arid the resulting list of statements 
will be assembled. For example, repeat could be a LAMBDA macro 
with two arguments, n and m, which expands into n occurrences of 
m, e.g. (REPEAT 3 (CAR!)) expands to ((CAR1) (CAR!) (CAR1)). The 
definition (i.e. value of property AMAC) for repeat is: 

(LAMBDA (N M) 
(PROG (YY) 
A (COND 

( ( I LESS P N 1) . 

(RETURN (CAR YY))) 
(T (SETQ YY (TCONC YY M) ) 
(SETQ N (SUB1 N) ) 
(GO A))))) 

If car of the macro definition is not the atom LAMBDA, it must be 
a list of dummy symbols. The arguments of the macro call will be 
substituted for corresponding appearances of the dummy symbols in 
cdr of the definition, and the resulting list of statements will 
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be assembled. 61 For example, ubox could be a substitution macro 
which takes one argument, a number, and expands into instructions 
to compile the unboxed value of this number and put the result on 
the number stack. 

The definition of UBOX is: 



((E) 
(CQ (VAG E)) 
(PUSH HP , 1)) 



Thus (UBOX (ADD1 X)) expands to: 



((CO (VAG (ADD1 X))) 
(PUSH NP p 1)) 



(4) special assemble statements - 

(CO Sj s 2 .-..) CO (compile quote) takes any number of arguments 

which are assumed to be regular S-expressions and 

are compiled in the normal way. E.g. 

(CO (COND ( (NULL Y) (SETQ Y 1))) 
(SETQ X (IPLUS Y Z))) 

Note: to avoid confusion, it is best to have as much of a function as possible 
compiled in the normal way, e.g. to load the value of x to AC1, (CO X) is 
preferred to (LDV (QUOTE X) SP), 

C (compile) takes any number of arguments which 
are first evaluated, then compiled in the usual 



(C s 1 s 2 . . . ) 



Note that assemble macros produce a list of statements to be assembled, 
whereas compiler macros produce a single expression. An assemble macro 
which computes a list of statements begins with LAMBDA and may be either 
spread or no-spread. The analogous compiler macro begins with an atom, 
(i.e. is always no-spread) and the LAMBDA is understood. 
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way. Both C and CQ permit the inclusion of 
regular compilation within an assemble form. 



(E ej e 2 . . . ) 



E (evaluate) takes any number of arguments which 
are evaluated in sequence. For example, (PSTEP) 
calls a function which increments the compiler 
variable SP. 



(SETQ var) 



Compiles code to set the variable var to the 
contents of AC1 . 



(FASTCALL fn) 



Compiles code to call fn. Fn must be one of the 
SUBR's that expects its arguments in the 
accumulators, and not on the push-down stack. 
Currently, these are cons , and the boxing and 

SP 

unboxing routines. 
Example : 

(CO X) 

(L0V2 (QUOTE Y) SP 2) 
(FASTCALL CONS) 

and cons[x,y] will be in AC1. 



(* ... ) 



* is used to indicate a comment; the statement is 
ignored. 



COREVALS 



There are several locations in the basic machine code of INTERLISP-10 which may 



52 



list may also be called with fastcall by placing its arguments on the 
pushdown stack, and the number of arguments in AC1 . 
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be referenced from compiled code. The current value of each location is stored 
on the property list under the property COREVAL. 63 Since these locations may 
change in different reassemblies of INTERLISP-10 , they are written symbolically 
on compiled code files, i.e. the name of the corresponding COREVAL is written, 
not its value. Some of the COREVALs used frequently in assemble are: 



CONS 


entry to function CONS 


LIST 


entry to function LIST 


KT 


contains (pointer to) atom T 


KNIL 


contains (pointer to) atom NIL 


MKN 


routine to box an integer 


M'KFN 


routine to box floating number 


IUNBOX 


routine to unbox an integer 


FUNBOX 


routine to unbox floating number 



ThQ index registers used for the push-down stack pointers are also included as 

COREVALS. These are not expected to change, and are not stored symbolically on 

compiled code files; however, they should be referenced symbolically in 
assemble code. They are: 

PP 
CP 
NP 

18.14 LAP 

LAP (for LISP assembly Processor) expands the output of the first pass of 
compilation to produce numerical machine instructions. 



The value of corevals is a list of all atoms with COREVAL properties. 



parameter stack 
control stack 
number stack 
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LAP Statements 



If a LAP statement is an atom, it is treated as a label identifying the 
location of the next statement to be processed. If a LAP statement is not ari 
atom, car of it must be an atom and one of the following: (1) a number ; (2) a 
machine instruction; or (3) a LAP macro. 

(1) numbers - If car of a LAP statement is a number > a location containing the 

number is produced in the object code. 

e.g. (ADD 1 , A (1)) 

a (i) - ■.. ... 

(4) 
(9) 

Statements of this type are processed like machine instructions, 
with the initial number serving as a 36-bit op-code > 

(2) Machine Instructions - If car of a LAP statement has a numeric value for 

the property OPD, 54 the statement is a machine instruction. The 
general form of a machine instruction is: 

(opcode ac , @ address (index)) 



Opcode is any PDP-10 instruction mnemonic or INTERLISP DUO. 55 



54 The value is an 18 bit quantity (rather than 9), since some UUO's also use 
the AC field of the instruction. 

66 The TEMEX JSYS's are not defined, that is, one must write ( JSYS 107) 
instead of (KFORK). 
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Ac , the accumulator field, is optional. However, if present, it 
must be followed by a comma, Ac is either a number or an atom 
with a COREVAL property. The low order 4 bits of the number or 
COREVAL are OR'd to the AC field of the instruction. 

& may be used anywhere in the instruction to specify indirect 
addressing (bit 13 set in the instruction) e.g. (HRRZ 1 , © * V). 

Address is the address field which may be any of the following: 

= constant Reference to an unboxed constant. A location 
containing the unboxed constant will be created in 
a region at the end of the function, and the 
address of the location containing the constant is 
placed in the address field of the current 
instruction. The constant may be a number e.g. 
(CAME 1 , = 3596); an atom with a property COREVAL 
(in which case the constant is the value of the 
property, at LOAD time); any other atom which is 
treated as a label (the constant is then the 
address of the labeled location) e.g. 
(MOVE 1 , = TABLE) is equivalent to 

(MOVE! 1 , TABLE); or an expression whose value is 
a number. 

1 pointer The address is a reference to a INTERLISP pointer, 

e.g. a list, number, string, etc. A location 
containing the pointer is assembled at the end of 
the function, and the current instruction will 
have the address of this location. E.g. 
(HRRZ 1 , • " IS NOT DEFINED" ) 
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(HRRZ 1 , • (NOT FOUND) ) 



* Specifies the current location in the compiled 

function; e.g. (JRST * 2) has the same effect as 
(SKIPA). 

literal atom If the atom has a property CORE VAL, it is a 
reference to a system location, e.g. 
(SKIPA 1 , KNIL), and the address used is the 
value of the coreval . Otherwise the atom is a 
label referencing a location in the LAP code, e.g. 
(JRST A). 

number The number is the address; e.g. 

(HOVSI 1 , 4000000) 
(HLRZ 2 , 1 (1)) 

list The form is evaluated, and its value is the 

address. 

Anything else in the address field causes an error message, e.g. 
(SKIPA 1 , KNILL) - LAPERROR. A number may follow the address 
field and will be added to it, e.g. (JRST A 2). 

Index is denoted by a list following the address field, i.e. the 
address field must be present if an index field is to be used. 
The index (car of the list) must be either a number, or an atom 
with a property COREVAL, e.g. 
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(HRRZ 1 o 0 (1)) or ( ANDM 1 , -1 (NP))« 



(3) LAP macros - If car of a LAP statement is the name of a LAP macro, i.e. 

has the property OPD, the statement is a macro call. The 
arguments of the call follow the macro name: e.g. (LQ2 FIE 3). 

LAP macro calls comprise most of the output of the first pass of 
the compiler, and may also be used in assemble . The definitions 
of these macros are stored on the property list under the 
property OPD, and like assembler macros, may be either lambda or 
substitution macros. In the first case, the macro definition is 
applied to the arguments of the call; 57 in the second case, the 
arguments of the call are substituted for occurrences of the 
dummy symbols in the definition. In both cases, the resulting 
list of statements is again processed, with macro expansion 
continuing till the level of machine instructions is reached. 

Some examples of LAP macros are shown in Figure 18-2. 



If assemble code is intended to be swappable (see section 3), indexing 
should not be used in instructions that refer to assemble labels. 

The arguments were already evaluated in the first pass, see page 18.37. 
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(DEFLIST(QUOTE( 
(SVN ( (N P) 

(MOVE 1 , ' N) 
(HRLM 1 , P (PP)))) 
(SVB ((N) 

(HRL 1 , ' N) 
( PUSH PP , 1 ) ) ) 
(LQ ((X) 

(HRRZ 1 , ' X))) 
(LQ2 ((X AC) 

(HRRZ AC , ' X))) 
(LDV ((A SP) 

(HRRZ 1 , (VREF A SP)))) 
(STV ((A SP) 

(HRRM 1 , (VREF A SP)))) 
(LDV2 ((A SP AC) 

(HRRZ AC , (VREF A SP)))) 
(LDF ((A SP) 

(HRRZ 1 , (FREF A SP)))) 
(STF ((A SP) 

(HRRM 1 , (FREF A SP)))) 
(LDF2 ((A SP) 

(HRRZ 2 , (FREF A SP)))) 
(CAR1 (NIL 

(HRRZ 1 , 0 (1)))) 
(CDR1 (NIL 

(HLRZ 1 , 0 (1)))) 
(CARQ ((V) 

(HRRZ 1,9' V))) 
(CARQ2 ( (V AC) 

(HRRZ AC , Q ' V))) 
( CAR2 ((AC) 

(HRRZ AC , 0 (AC)))) 
(RPO ((V) 

(HRRM 1,9' V) 
(CLL ((NAM N) 

(CCALL N , 'NAM))) 
(LCLL ((NAM N) 

(LNCALL N , (MKLCL NAM)))) 
(STE ( ( TY) 

(PSTE1 TY))) 
(STN ((TY) 

(PSTN1 TY))) 
(RET (NIL 

(POPJ CP , ) 
(PUSHP (NIL (PUSH PP , 1))) 
(PUSHQ ((X) 

(PUSH PP , ' X))) 
)) (QUOTE OPD)) 



(* STORE VARIABLE NAME) 

(* STORE VARIABLE NAME AND VALUE) 

(* LOAD QUOTE TO AC1) 

(* LOAD QUOTE TO AC) 

(* LOAD LOCAL VARIABLE TO AC1) 

(« SET LOCAL VARIABLE FROM AC1) 

(" LOAD LOCAL VARIABLE TO AC) 

(« LOAD FREE VARIABLE TO AC1) 

(« SET FREE VARIABLE FROM AC1) 

(" LOAD FREE VARIABLE TO AC) 

(« CAR OF AC1 TO AC1) 

(* CDR OF ACl TO AC1) 

( 9 CAR QUOTE) 

(* CAR QUOTE TO AC) 

(.* CAR OF AC TO AC) 

(« RPLACA QUOTE) 

(* CALL FN WITH N ARGS GIVEN) 

(* LINKED CALL WITH N ARGS) 

(» SKIP IF TYPE EQUAL) 

(* SKIP IF TYPE NOT EQUAL) 

(* RETURN FROM FN) 

(« PUSH QUOTE) 



Figure 18-2 
Examples of LAP Macros 
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18.15 Using Assemble 



In order to use assemble , it is helpful to know the following things about how 
compiled code is run. All variable bindings and temporary values are stored on 
the parameter pushdown stack. When a compiled function is entered, the 
parameter pushdown list contains, in ascending order of address: 

1. bindings of arguments to the function, where each binding occupies one 
word on the stack with the variable name in the left half and the 
value in the right half. 

2. pointers to the most recent bindings of free variables used in the 
function. 

The parameter push-down list pointer, index register PP, points to the last 
free variable pointer on the stack. 

Temporary values, PROG and LAMBDA bindings, and the arguments to functions 
about to be called, are pushed on the stack following the free variable 
pointers. The compiler uses the value of the variable SP to keep track of the 
number of stack positions in use beyond the last free variable pointer, so that 
it knows where to find the arguments and free variable pointers. The function 
PSTEP adds 1 to SP, and PSTEPN(N) adds N to SP (N can be positive or negative). 

The parameter stack should only be used for storing pointers. In addition, 
anything in the left half of a word on the stack is assumed to be a variable 
name (see Section 12). To store unboxed numbers, use the number stack, NP. 
Numbers may be PUSH'ed and POP'ed on the number stack. 
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18.16 Miscellaneous 

The value of a function is always returned in AC1. Therefore, the pseudo- 
function, ac, is available for obtaining the current contents of AC1. For 
example (CQ (F00 (AC))) compiles a call to F00 with the current contents of AC1 
as argument, and is equivalent to: 



In using ac, be sure that it appears as the first argument to be evaluated in 
the expression. For example: (CO (IPLUS (LOC (AC)) 2)) 



There are several ways to reference the values of variables in assemble code. 
For example: 



(PUSHP) 

(E (PSTEP)) 

(CLL (QUOTE F00) 1) 

(E (PSTEPN -I)')" 



n 



to put value of X in AC1: 



(CO X) 



to put value of X in ACS: 



(LDV2 (QUOTE X) SP 3) 



to set X to contents of AC1: 



(SETQ X) 



to set X to contents of AC2: 



(E (STORIN (LIST (QUOTE HRRM) 2 (QUOTE ,) 
(LIST (VARCOMP (QUOTE X)) 
(QUOTE X) 
SP)))) 



to box and unbox a number: 



(CQ (LOC (AC))) 
(FASTCALL MKN) 
(FASTCALL MKFN) 
(CQ (VAG X)) 



box contents of AC1 
box contents of AC1 
floating box contents of AC1 
unboxed value of X to AC1 
unbox contents of AC1 
floating unbox of AC1 



(FASTCALL IUNBOX) 
(FASTCALL FUNBOX) 
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To call a function directly, the arguments must be pushed on the parameter 
stack, and 5P must be updated, and then the function called: e.g. 



(CO (CAR X)) 
(PUSHP) 
(E (PSTEF)) 
(PUSHQ 3.14). 
(E (PSTEP)) 
(CLL (QUOTE FUH) 2) 
(E (PSTEPN -2)) 

and is equivalent to: 

(CQ (FUM (CAR X) 3,14)) 

18.17 Compiler Printout and Error Messages 

For each function compiled, whether from tcompt , recompile , or compile , tho 
compiler prints: 

(fn COMPILING) 

(fn (arg 1 ... arg n ) (free i ... free n )) 

The first message is printed when the compilation of fn begins. The second 
message is printed at the beginning of the second pass of the compilation of 
fn. (arg 1 ... arg n ) is the list of arguments to fn, and (freej ... free n ) tho 
list of free variables referenced or set in fn. The appearance of non- 
variables, e.g. function names, words from a comment, etc. in (freej ... free n ) 
is a good indication of parenthesis errors. 

If the compilation of fn causes the generation of one or more gensyro functions 
(see page 18.18), compiler messages will be printed for these functions botwoen 
the first message and the second message for fn, e.g. 



Does not include global variables, see page 18.6. 



(* stack first argument) 



(* stack second argument) 

(** call FUM with 2 arguments) 

(* adjust stack count) 
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(FOO COMPILING) 
(FOOA0027 COMPILING) 
(FOOA0027 NIL (X)) 
(FOO (X) NIL) 

The compiler output for block compilation is similar to normal compilation. 
The pass one message, i.e. (fn compiling) is printed for each Junction in the 
block. Then a second pass message is printed for the entire block. ^ 9 Then both 
messages are printed for each entry to the block. 

In addition to the above output, both recompile and brecompile print the name 
of each function that is being copied from the old compiled file to the new 
compiled file. The normal compiler messages are printed for each function that 
is actually compiled. 

Compiler Error Messages 

Messages describing errors in the function being compiled are also printed on 
the teletype. These messages are always preceded by Unless otherwise 

indicated below, the compilation will continue. 

((form) - NON ATOMIC CAR OF FORM) 

If user intended to treat the value of form as a function, he should 
use apply* . form is compiled as if apply* had been used. See Section 
8. 

(fn - NO LONGER INTERPRETED AS FUNCTIONAL ARGUMENT) 

The compiler has assumed fn is the name of a function. If the user 



The names of the arguments to the block are generated by suffixing 1 # 1 and 
a number to the block name, e.g. 

(FOOBLOCK (FOOBLOCK#0 FOOBLOCK#l) free-variables ) . 
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intended to treat the value of fn as a function, he must use ap ply* 
See Section 8. 60 



(tg - MULTIPLY DEFINED TAG) 

tcj is a PROG label that is defined* more than once in a single PROG. 
The second definition is ignored. 

(tg - UNDEFINED TAG) 

tcj is a PROG label that is referenced but not defined in a PROG. 

(tg - MULTIPLY DEFINED TAG, ASSEMBLE) 

tg is a label that is defined more than once in an assemble form. 

(tg - UNDEFINED TAG, ASSEMBLE) 

tg is a label that is referenced but not defined in an ASSEMBLE form. 

(tg - MULTIPLY DEFINED TAG, LAP) 

tg is a label that was encountered twice during the second pass of the 
compilation. If this error occurs with no indication of a multiply 
defined tag during pass one, the tag is in a LAP macro. 

(tg - UNDEFINED TAG, LAP) 

tcj is a label that is referenced during the second pass of compilation 
and is not defined. LAP treats tg as though it were a coreval , and 
continues the compilation. 



This message is printed when fn is not defined, and is also a local 
variable of the function being compiled. Mote that earlier versions of tho 
INTERLISP compiler did treat fn as a functional argument, and compiled code 
to evaluate it. 
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(fn - USED AS ARG TO NUMBER FN?) 

The value of a predicate, such as GREATERP or EQ, Is used as an 
argument to a function that expects numbers, such as I PLUS. 

IS GLOBAL) 

* is a global variable , and is also rebound in the function being 
compiled, either as an argument or as a local variable. The error 
message is to alert the user to the fact that other functions will not 
see this binding, s;lnce x is always accessed directly through its 
value cell. 

(op - OPCODE? - ASSEMBLE) 

op appears as car of an assemble statement, and is illegal. See page 
18.30-40 for legal assemble statements. 

(blknane - USED BLKAPPLY WHEN NOT APPLICABLE) 

blkapply is used in the block blkname , but there are no blkapplyf ns or 
entries declared for the block. 

(fn - ILLEGAL RETURN) 

return encountered when not in prog . 

(tg - ILLEGAL GO) 

go encountered when not ill a prog . 

(fn NOT COMPILEABLE) 

An expr definition for fn could not be found. In this case, no code 
is produced for fn, and the compiler proceeds to the next function to 
be compiled, if any. 

fn NOT COMPILEABLE. 



(x - 
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Same as above except generates an error, thereby aborting all 
compilation. For example, this error condition occurs if fn is one of 
the functions in a block. 

fn NOT FOUND. 

Occurs when recompile or brecompile try to copy the compiled 
definition of fn from cfile, and cannot find it. See page 18.53, 
Generates an error. 

fn NOT ON BLKFNS. 

fn was specified as an entry to a block, or else was on blkapplyfns , 
but did not appear on the blkfns . Generates an error. 

fn CAN'T BE BOTH AN ENTRY AND THE BLOCK NAME. 
Generates an error. 

(fn NOT IN FILE - USING DEFINITION IN CORE) 
on calls to bcompl and brecompile . 
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SECTION 19 
ADVISING 



The operation of advising gives the user a way of modifying a function without 
necessarily knowing how the function works or even what it does. Advising 
consists of modifying the interface between functions as opposed to modifying 
the function definition itself, as in editing, break , trace , and breakdown , 
are examples of the use of this technique: they each modify user functions by 
placing relevant computations between the function and the rest of the 
programming environment. 

The principal advantage of advising, aside from its convenience, is that it 
allows the user to treat functions, his or someone else's, as "black boxes," 
and to modify them without concern for their contents or details of operations. 
For example, the user could modify sysout to set sysdate to the time and date 
of creation by advise[ SYSOUT ; ( SETQ SYSDATE (DATE))] 

As with break , advising works equally well on compiled and interpreted 
functions. Similarly, it is possible to effect a modification which only 
operates when a function is called from some other specified function, i.e., to 
modify the interface between two particular functions, instead of the interface 
between one function and the rest of the world. This latter feature is 
especially useful for changing the internal workings of a system function. 



Advising was developed and implemented by W. Teitelman. 
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For example, suppose the user wanted time (Section 21) to print the results of 
his measurements to the file F00 instead of the teletype- He could accomplish 
this by ADVISE(((PRIN1 PRINT SPACES) IN TIME) BEFORE (SETQQ U FOG)) 

Mote that advising print , print , or spaces directly would have affected all 
calls to these very frequently used function, whereas advising 
( (PRIN1 PRINT SPACES) IN TIME ) affects just those calls to prinl , print, and 
spaces from time . 

Advice can also be specified to operate after a function has been evaluated. 
The value of the body of the original function can be obtained from the 
variable ! value , as with breakl . For example, suppose the user wanted to 
perform some computation following each sysin , e.g. check whether his files 
were up to date. He could then: 

ADVISE(SYSOUT AFTER (COND ((LISTP ! VALUE) --))) 2 
19.1 Implementation of Advising 

The structure of a function after it has been modified several times by adviso 
is given in the following diagram: 



After the sysin , the system will be as it was when the sysout was 
performed, hence the advice must be to sysout , not sysin . See Section 14 
for complete discussion of sysout/sysin . 
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The corresponding 1NTERL1SP definition is: 



(LAMBDA arguments (PROG ( ! VALUE) 
(SETQ ! VALUE (PROG MIL 
advice! 



advicen 

(RETURN body))) 
advice! 



ADVICE 
BEFORE 



ADVICE 
AFTER 



advicem 

(RETURN (VALUE))) 



where body is equivalent to the original definition 



3 4 



Note that the structure of a function modified by advise allows a piece of 
advice to bypass the original definition by using the function RETURN. For 
example, if (COND ( (ATOM X) (RETURN Y))) were one of the pieces of advice 
BEFORE a function, and this function was entered with x atomic, y would be 
returned as the value of the inner PROG, lvalue would be set to and control 
passed to the advice, if any, to be executed AFTER the function. If this same 
piece of advice appeared AFTER the function, ^ would be returned as the value 
of the entire advised function. 



The advice (COND ((ATOM X) (SETQ IVALUE Y) ) ) AFTER the function would have a 
similar effect, but the rest of the advice AFTER the function would still be 
executed. 



Actually, advise uses its own versions of PROG, SETQ, and RETURN, (called 
ADV-PROG, ADV-SETQ, and ADV-RETURN) in order to enable advising these 
functions. 

If fn was originally an EXPR, body is the body of the definition, otherwise 
a form using a gensym which is defined with the original definition. 
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19.2 Advise Functions 



Advise 

Advise is a function of four arguments: fn, when , where , and what, fn is tho 
function to be modified by advising, what is the modification, or piece of 
advice, when is either BEFORE, AFTER, or AROUND, and indicates whether the 
advice is to operate BEFORE, AFTER, or AROUND the body of the function 
definition, where specifies exactly where in the list of advice the new advice 
is to be placed, e.g., FIRST, or (BEFORE PRINT) meaning before the advice 
containing print , or (AFTER 3) meaning after the third piece of advice, or even 
(: TTY : ) . If where is specified, advise first checks to see if it is one of 
LAST, BOTTOM, END, FIRST, or TOP, and operates accordingly. Otherwise, it 
constructs an appropriate edit command and calls the editor to insert the 
advice at the corresponding location. 

Both when and where are optional arguments, in the sense that they can be 
omitted in the call to advise . In other words, advise can be thought of as a 
function of two arguments [fn;what], or a function of three arguments: 
[ fn ;when ;what ], or a function of four arguments: [fn;when;where;what ]. Note 
that the advice is always the last argument. If when ^NIL, BEFORE is used. If 
v;here = NIL, LAST is used. 

advise[fn;when;where;what] fn is the function to be advised, when=BEFORE, 

AFTER, or AROUND, where specifies where in the 
advice list the advice is to be inserted, and what 
is the piece of advice. 

If fn is of the form (fnl IN fn2), fnl, is changed 
to fnWN-fn2 throughout fn2, as with break, and 
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then fnl-IN-fn2 is used in place of fn. 



If fn is broken, it is unbroken before advising. 

If fn is not defined, an error is generated, 
NOT A FUNCTION. 

If fn is being advised for the first time, i.e. if 
getp[name, APVISEP3=NIL, a gensyro is generated and 
stored on the property list of fn under the 
property ADVISED, and the gensym is defined with 
the original definition of fn. An appropriate S* 
expression definition is then created for fn. 6 
Finally, fn is added to the (front of) 
advisedfns 7 

If fn has been advised before, it is moved to the 
front of advisedfns . 

If whensBEFORE or AFTER, the advice is inserted 
in fn's definition either BEFORE or AFTER the 
original body of the function. Within that 
context, its position is determined by where . If 



If f nl and/or fn2 are lists, they are distributed as shown in the example 
on page 19.2. 



Using private versions of PROG, SETQ, and RETURN, so that these functions 
can also be advised. 



So that unadvise[T] always unadvises the last function advised. See page 
19.8. 
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where sLAST, BOTTOM 9 END, or MIL, the advice is 
added following all other advice, if any. If 
wheres FIRST or TOP, the advice is inserted as the 
first piece of advice. Otherwise, where is 
treated as a command for the editor, a la breakin , 
e.g. (BEFORE 3), (AFTER PRINT) .. 

If whens AROUND, the body is substituted for ft in 
the advice, and the result becomes the new body, 
e.g. advise[ FOO ; AROUND ; ( RESETFORM (OUTPUT T) *)]. 
Note that if several pieces of AROUWD advice are 
specified, earlier ones will be embedded inside 
later ones. The value of where is ignored. 

Finally list[when;where ;what] is added (by 
addprop ) to the value of property ADVICE on the 
property list fn.* Mote that this property value 
is a list of the advice in order of calls to 
advise, not necessarily in order of appearance of 
the advice in the definition of fn. 

The value of advise is fn. 

If fn is non-atomic, every function in fn is 
advised with the same values (but copies) for 
when , where , and what . In this case, the value of 
advise is a list of individual functions. 



So that a record of all the changes is available for subsequent use in 
readvising, see page 19.8. 
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Note: advised functions can be broken. (However if a function is broken at 
the time it is advised, it is first unbroken.) Similarly, advised functions can 
be edited, including their advice, unadvise will still restore the function to 
it's unadvised state, but any changes to the body of the definition will 
survive . Since the advice stored on the property list is the same structure as 
the advice inserted in the function, editing of advice can be performed on 
either the function's definition or its property list. 

unadvise[x] is a no-spread NLAMBDA a la unbreak . It takes an 

indefinite number of functions and restores them 
to their original unadvised state, including 
removing the properties added by advise . g unadvise 
saves on the list advinfolst enough information to 
allow restoring a function to its advised state 
using readvise . advinfolst and readvise thus 
correspond to brkinfolst and rebreak . 

unadvise[ ] unadvises all functions on 
advisedfns .^ It first sets advinfolst to NIL. 

unadvise[T] unadvises the first function of 
advisedfns , i.e., the most recently advised 
function. 

readvise[x] is a no-spread NLAMBDA a la rebreak for restoring 
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Except if a function also contains the property READVICE (see r eadvise 
below), unadvise moves the current value of the property ADVICE to 
READVICE. 

In reverse order, so that the most recently advised function is unadvised 
last. 
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a function to its advised state without having to 
specify all the advise information. For each 
function on x» readvise retrieves the advise 
information either from the property READVICE for 
that function, or from advinfolst , and performs 
the corresponding advise operation( s) . In 
addition it stores this information on the 
property READVICE if not already there. If no 
information is found for a particular function, 
value is (fn - NO ADVICE SAVED). 

readvise[] readvises everything on advinfolst . 

readvise[T] readvises just the first function on 
advinfolst , i.e., the function most recently 
unadvised. 

A difference between advise , unadvise , and readvise versus break , unbreak , and 
rebreak , is that if a function is not rebroken between successive unbreak[ ] 1 s , 
its break information is forgotten. However, once readvised, a function's 
advice is permanently saved on its property list (under READVICE); subsequent 
calls to unadvise will not remove it. In fact, calls to unadvise update the 
property READVICE with the current value of the property ADVICE, so that the 
sequence readvise, advise , unadvise causes the augmented advice to become 
permanent. Note that the sequence readvise , advise , readvise removes the 
'intermediate advice 1 by restoring the function to its earlier state. 

advisedump[x;f Ig] Used by prettydef when, given a command of the form 

(ADVISE --) or (ADVICE --). flcpT corresponds to 
(ADVISE --), i.e. advisedump writes both a def list 
and a readvise , f lg=NIL corresponds to (ADVICE 
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) , i.e. only the def list is written. In either 
case, advisedump copies the advise information to 
the property READVICE, thereby making it 
'permanent' as described above. 
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SECTION 20 
PRINTSTRUCTURE, INTERSCOPE, AND HELPSYS 



20 . 1 Printstructure 

In trying to work with large programs, a user can lose track of the hierarchy 
which defines his program structure; it is often convenient to have a map to 
show which functions are called by each of the functions in a system. If fn is 
the name of the top level function called in your system, then typing in 
printstructure[fn] will cause a tree printout of the function-call structure of 
fn . To illustrate this in more detail, we use the printstructure program 
itself as an example. 



A preliminary version of printstructure was written by D. G. Bobrow, The 
current form of printstructure was written by W. Teitelman. 
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PRINTSTRUCTURE PRGETD 

PROGSTRUC PRGETD 

PRGSTRC NOTFN PRGETO 
PROGSTRUC 
PRGSTRC1 PRNCONC 
PRGSTRC1 
PRGSTRC 

PRNCONC 
PRGSTRC 
CALLS1 MAKELIST 
NOTFN 

CALLS2 CALLS 1 
PRGETO 

TREEPRINT TREEPRINT1 

TREEPRINT 
VARPRINT VARPRINT1 TREEPRINT1 

VARPRINT2 ALLCALLS ALLCALLS1 ALLCALLSl 

TREEPRINT1 

+ + + + + + + + + + + + + + + + + + + + + +++++ + **++++ + 4-++ + ++^ 

PRINTSTRUCTURE [X, FILE : DONELST , N , TREELST , TREEFNS, LSTEM ,X,Y,Z, 

FN, TREE ; PRDEPTH , LAST- PRINTSTRUCTURE ] 
CALLED BY: 

PRGETD [X.FLG; ; ] 

CALLED BY: PRINTSTRUCTURE , PROGSTRUC , NOTFN, CALLS2 

PROGSTRUC [FN.DEF; N , Y , Z , C AL LSF LG , VARSF LG , VARS 1 , VARS2 , D , X ; N, DONELST] 
CALLED BY: PRINSTRUCTURE .PRGSTRC 

PRGSTRC [X.HEAD.FLG; Y.TEM.X; VARSFLG , D , NOFNS , CALLSFLG , N . DONELST , 
TREEFNS, MOTRACEFNS, FN, VARSl.QUOTEFNS] 
CALLED BY : PROGSTRUC , PRGSTRC1 , PRGSTRC 

NOTFN [FN; DEF; NOFNS , YESFNS , FIRSTLOC , LASTLOC ] 
CALLED BY: PRGSTRC, CALLS 1 

PRGSTRC1 CL.HEAD.FLG; A.B; VARS 1 , VARS2 ] 
CALLED BY: PRGSTRC, PRGSTRC1 

PRNCONC [X,Y; ; CALLSFLG] 

CALLED BY: PRGSTRC! , PRGSTRC 

CALLS1 [ ADR, GENFLG, D ; LIT,END,Vl,V2,LEFT,OPD,X,X; VARS1.VARS2, 
VARSFLG] 

CALLED BY: PROGSTRUC, CALLS2 

MAKELIST [N.ADR; L; ] 
CALLED BY: CALLS1 



Figure 20-1 
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The upper portion of this printout is the usual horizontal version of a troo. 
This tree is straighf orwardly derived from the definitions of the functions: 
printstructure calls prgetd , progstruc , treeprint , and varprint . progstruc in 
turn calls prgetd , prgstrc and callsl > prgstrc calls notfn , progstruc . 
prgstrcl , prnconc , and itself, prgstrcl calls prnconc 0 itself, and prgstrc . 
Note that a function whose substructure has already been shown is not expanded 
in its second occurrence in the tree. 

The lower portion of the printout contains, for each function, information 
about the variables it uses, and a list of the functions that call it. For 
example, printstructure is a function of two arguments, x and file. It binds 
eleven variables internally: donelst , n , ... tree , and uses prdepth and 
last -printstructure as free variables. It is not called by any of the 
functions in the tree, prgetd is a function of two arguments, x and fig , binds 
no variables internally, uses no free variables, and is called by 
printstructure , progstruc , notfn and calls2. 

printstructure calls many other low-level functions such as getd , car, list , 
nconc , etc. in addition to the four functions appearing in the above output. 
The reason these do not appear in the output is that they were defined 
"uninteresting" by the user for the purposes of his analysis. Two functions, 
f irstf n and lastfn , and two variables, yesfns and nofns are used for this 
purpose. Any function that appears on the list nofns is not of interest, any 
function appearing on yesfns is of interest. 

yesfns =T effectively puts all functions on yesfns . As for functions appearing 
on neither nofns or yesfns , all interpreted functions are deemed interesting, 
but only those compiled functions whose code lies in that portion of bpspace 



Variables are bound internally by either PROGs LAMBDA-expressions . 
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between the two limits established by f irstfn and lastfn . For example, the 
above analysis was performed following first fn[ PRINTSTRUCTURE ] and 
lastf n[ ALICALLS1 ] . 

Two other variables, notracefns and prdepth, also affect the action of 
printstructure . Functions that appear on the list notracefns will appear in 
the tree, assuming they are "interesting" functions as defined above, but their 
definitions will not be analysed, prdepth is a cutoff depth for analysis. It 
is initially set to 7. 

printstructure assumes that all functions whose argtypes are 1 or 3, i.e. all 
MLANBDAs, do not evaluate their arguments. For example, if the function prinq 
were defined as (NLAMBDA (X) (MAPC X (FUNCTION PRINl))), and the form 
(PRINQ (NOW IS THE TIME ) ) appeared in a function being analyzed, IS, THE, and 
TIME would not be reported as free variables, and NOW as an undefined function. 
The user can inform printstructure (and other system packages which require 
this information) that an nlambda function does evaluate its arguments by 
putting on its property list the property INFO value EVAL. For example, the 
functions and , ersetq , progn, etc., are all initialized in this fashion. 

If printstructure encounters a form beginning with two left parentheses in the 
course of analyzing an interpreted function (other than a COND clause or open 
lambda expression) it notes the presence of a possible parentheses error by the 
abbreviation P.P.E. , followed by the function in which the form appears, and 
the form itself, as in the example below. Note also that since printstructure 
detects functions that are not defined, (i.e., atoms appearing as CAR of a 
f orm) , printstructure is a useful tool for debugging. 
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<-PP FOO 

(FOO 

[LAMBDA (X) 
(COND 

( (CAR X) (FOOl X}) 
(T ( ( CONS X (CAR X]) 

FOO 

-PRINTSTRUCTURE(FOO) 
FOO FOOl 

-;- •:- ■*■■>■>-;■ <■ -;• •;- •:- •;• •:■ •;• •;• •> •:• •:- •:• •;• •;• •:- •.• ■> ■:• •;• v v v * * •> •;- •;• •;• v •>•>•!•■;• v •:• v •:• •:• <- •;• •:- ■> •> -> •> •;■ •>■>■> •> •;• •;• * •> -> * + <» •;• •:- 

FOO [X; ; ] 

CALLED BY: 

FOOl IS NOT DEFINED • 

P.P.E. IN FOO - {(CONS X (CAR X))) 

Figure 20-2 

Other Options 

printstructure is a function of three arguments, x P exprf lg > and file. 
printstructure analyzes x, sets the free variable last- printstructure to the 
results of its analysis, prints the result (in the format shown earlier) to 
file (which is opened if necessary and closed afterwards), and returns x as its 
value. Thus if the user did not want to see any output, he could call 
printstructure with f ile sNXL: , and then process the result himself by using 
last-printstructure . 

printstructure always checks for EXPR properties on the property list of 
functions that are not defined. However, if exprf Ig sT, printstructure will 



NIL: is a TENEX output device that acts like a 'bottomless pit'. Note 
that f ile =NIL (not NIL:) means print the tree to primary output file. 
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prefer to analyze EXPR definitions whenever possible, i.e. if the function 
definition call contains a compiled definition, and there is also an EXPR 
property, the latter will be analyzed. 

x can be NIL, a list, a function, or an atom that evaluates to a list. If x is 
NIL, printstructure does not perform any analysis, but simply prints the result 
of the last analysis, i.e., that stored on las t-pr in t structure . Thus the user 
can effectively redirect the output that is going to the terminal to a disc 
file by aborting the printout, and then performing printstructure[NIL;f ile]. 

If x is a list, printstructure analyzes the first function on x ( and then 
analyzes the second function, unless it was already analyzed, then the third, 
etc., producing however many trees required. Thus, if the user wishes to 
analyze a col lection of functions, e.g., breakfns , he can simply perform 
(PRINTSTRUCTURE BREAKFNS). 

If x is not a list, but is the name of a function, printstructuret x] is the 
same as printstructure[ (x) ]. Finally, if the value of x is a list of 
functions, printstructure will process that list as described above. 

Note that in the case that x is a list, or evaluates to a list, subsequent 
functions are not separately analyzed if they have been encountered in the 
analysis of a function appearing earlier on the list. Thus, the ordering of x 
can be important. For example, if both F00 and FIE call FUM , 
printstructure[ (F00 FIE FUM)], will produce a tree for F00 containing embedded 
in it the tree for FUM. FUM will not be expanded in the tree for FIE, nor will 
it have a tree of its own. (Of course, if F00 also calls FIE, then FIE will 
not have a tree either.) The convention of listing FUM can be used to force 
printstructure to give FUM a tree of its own. Thus 
printstructure[(FOO FIE (FUM))] will produce three trees, and neither of the 
calls to FUM from FOO or FIE will be expanded in their respective trees. Of 
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course, in this example, the same effect could have been achieved by 
reordering, i.e., printstructure[ (FUM F00 FIE) ]. However, if TOO, FIE, and 
FUM, all called each other, and yet the user wanted to see three soparato 
trees, no ordering would suffice. Instead, the user would have to do 
printstructure[((FOO) (FIE) (FUM))]. 

The result of the analysis of printstructure is in two parts: donelst , a list 
summarizing the argument/variable information for each function appearing in 
the tree(s), and treelst , a list of the trees, last-prlntstructure is set to 
cons[ donelst ;treelst]. 

donelst is a list consisting, in alternation, of the functions appearing in any 
tree, and a variable list for that function, car of the variable list is a 
list of variables bound in the function, and cdr is a list of those variables 
used freely in the function. Thus the form of donelst for the earlier example 
would be: 

(PRINTSTRUCTURE ((X FILE DONELST N TREELST TREEFNS L TEM HZ 
FN TREE) PRDEPTH LAST- PRINTSTRUCTURE ) PRGETO ( ( X FLG) ) 
PROGSTRUC (( FN DEF N Y Z CALLSFLG VARSFLG VARS1 VARS2 D X) 
N DONELST) ... ALLCALLS1 ((FN TR A B))) 

Possible parentheses errors are indicated on donelst by a non-atomic form 
appearing where a function would normally occur, i.e., in an odd position. The 
non-atomic form is followed by the name of the function in which the P.P.E, 
occurred. 
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Printstructure Functions 



printstructure[x;exprf lg;f ile] analyses x, saves result on 

iast~printstructure , outputs trees and variable 
information to file , and returns x as its value. 

If exprf Ig sT, printstructure will prefer to 
analyze expr's. See page 20.5. 

treeprint[x;n] prints a tree in the horizontal fashion shown in 

the examples above, i.e., printstructure performs 
(MAPC TREELST (FUNCTION TREEPRINT) ) . 

varprint[donelst ; treelst] prints the "lower half" of the printstructure 

output. 

allcalls[fn;treelst] uses treelst to produce a list of the functions 

that call fn. 

firstfn[fn] If fn=T, lower boundary is set to 0, i.e., all 

subrs and all compiled functions will pass this 
test. If fnsNIL, lower boundary set at end of 
bpspace, i.e., no compiled functions will pass 
this test. Otherwise fn is the name of a compiled 
function and the boundary is set at fn, i.e., all 
compiled functions defined earlier than fn are 
rejected. 

lastfn[fn] if fn*NIL, upper boundary set at end of bpspaco , 

i.e. , all compiled functions will pass this test . 
Otherwise boundary set at fn, i.e., all compiled 
functions defined later than fn are rejected. 
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Thus to accept all compiled functions, perform firstfn[T] and lastfn[NIL]: to 



reject all compiled functions, perform firstfn[]. 



calls[ fn ;exprf lg;varsf Ig] 



is a fast 'one-level* 



printstructure , i.e., it 



indicates what functions fn calls, but does not go 
further and analyze any of them, c alls does not 
print a tree, but reports its findings by 
returning as its value a list of three elements: a 
list of all functions called by fn, a list of 
variables bound in fn, and a list of variables 
used freely in fn, e.g., 

calls[progstruc] = ( ( PRGETD EXPRP PRGSTRC CCODEP 
CALLS1 ATTACH) (FN DEF N Y Z CALLSFL6 VARSFLG 
VARS1 VARS2 D X) (N DONELST) ) 

fn can be a function name, a definition, or a 
form. Calls first does firstfn(T), lastfn() so 
that all subrs and compiled functions appear, 
except those on nofns. If varsf Ig is T, calls 
ignores functions and only looks at the variables 
(and therefore runs much faster). 



vars[ fn ;exprf Ig] 



cdr[calls[fn;exprf lg;T]] 



f reevars[ fn ;exprf Ig] 



cadr[ vars[ f n ; expr f lg ] ] 



20.9 



20.2 Interscope' 



While printstructure is a convenient tool for giving the user an overview of 
the structure of his programs* it is not well suited for determining the answer 
to particular questions the user may have about his programs. For example , if 
FOO uses X freely, and the user wants to know where X is bound 'above* FOO, he 
has to visually trace back up the tree that is output by printstructure , and. 
at each point, look down at the lower portion of the printout and find whether 
the corresponding function binds X. For large systems, such a procedure can be 
quite tedious. Furthermore, printstructure does not even compute certain 
certain important types of information. For example, printstructure does not 
distinguish between functions that use a variable freely and those that set it 
(or smash it) . 

Interscope is an extension of printstructure designed to resolve these 
shortcomings. Like printstructure , interscope analyses programs (functions), 
although it extracts considerably more information and relationships than does 
printstructure . However, instead of presenting the information it obtains in a 
predetermined format, interscope allows the user to ask it questions about the 
programs it has analysed, i.e. to interrogate its data base. These questions 
can be input in English, and contain conjunctions, disjunctions, and negations 
of the many relationships between functions and variables that interscope knows 
about. The questions can be closed questions, e.g. "DOES FOO CALL FIE?" , or 
open questions, "WHAT FUNCTIONS CALL FIE?". The answers to some questions are 
obtainable directly from the data base, e.g. "WHAT VARIABLES DOES FOO SET?" 
Other questions cause interscope to search its data base, e.g. 
"WHAT FUNCTIONS BIND VARIABLES THAT FOO SETS?". Figure 20-3 contains a sample 
session with interscope. 



Interscope was originally written by P. C. Jackson, and substantially 
revised and improved by L. M. Masinter . 
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-INTERSCOPE] 

Hello, shall I analyze a system? [1] 
&-WTFIXFNS AND CLISPFNS. 
This may take a few minutes. 

GC: 8 

1233, 10431 FREE WORDS 

Shall I analyze another system? 
&-HO [2] 

Ok, v/hat would you Hke to know? 
&WHO CALLS RETDWIM? 

(WTFIX FIX89TYPEIN FIXAPPLY FIXATOM FIXCONTINUE CLISPATOM FIXT) 
&HOW IS CLISPATOM CALLED? 

I didn't understand that. [3] 
&WHAT FUNCTIONS CALL CLISPATOM? [4] 
(WTFIX FIXAPPLY FIXATOM) 
&WHAT FREE VARIABLES DOES CLISPATOM USE? 

(ONLYSPELLFLG CLISPCHANGES CLISPFLG TYPE-IN? CLISPSTATS INFIXSTATS LST 
FAULTXX CHCOMLST FAULTX DWIMIFYFLG 89CHANGE FAULTPOS) 
&WHO BINDS TAIL? 

(WTFIX RETDWIM1 RETDWIM2 RETDWIM3 CLISPFUNCTION? CLISPATOMO CLISPATOM1 

CLISPATOM1A CLISPATOM2A DWIMIFY1A DWIMIFY2 DWIMIFY2A CLISPRESPELL) 

&WHO BINDS TAIL AND CALLS CLISPATOM SOMEHOW? 

(WTFIX DWIMIFY2 ) 

&WHAT VARS DOES HELPFIX CHANGE? 

(FORM LASTPOS NOCHANGEFLG HELPFIXTAIL FN TEM BRKEXP) 
&WHAT FUNCTIONS CHANGE THE VARIABLE TENTATIVE? 
(CLISPATOM1 CLISPATOM2 CLISPATOM2C CLISPATOM2A CLISPATOM1A) 
&WHO CHANGES TAIL? 

(FIXATOM HELPFIX1 CLISPAT0M1 CLISPAT0M2 DWIMIFY2) 
&WHAT FNS USE TEM AS AN INTERANL VAR AND 
...ARE CALLED BY CLISPATOM INDIRECTLY? 
I NTE RAN L= INTERNAL ? Yes 
(RETDWIM RETDWIM1 FIX89TYPEIN) 
&HOW DOES CLIAPTOM CALL LISTP? 
CLIAPTOM=CLISPATOM ? Yes 

((CLISPATOM LISTP) (CLISPATOM *«* RETDWIM *«« LISTP) (CLISPATOM C5] 
FIX89 FIX89A LISTP)) 

&SHOW ME THE PATHS FROM CLISPATOM TO LISTP. . 
CLISPATOM LISTP 

RETDWIM LISTP [6] 
RETDWIM1 LISTP 

FIX89TYPEIN RETDWIM .. . 

FIX89 FIX89A LISTP 
&DOES GETVARS SMASH ANY VARIABLES? 
(L) 

&SHOW ME HOW GETVARS SMASHES L. 

(NCONC L (AND (LISTP X) (MAPCAR & &))) 
&GOODBYE. 

Goodbye . 



Figure 20-3 
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In order to answer questions about programs, interscope must analyze thorn and 
build its data-base. When interscope is first called, it will ask the user 
what functions he wants analysed. The user can respond to this question by 
giving interscope either: 1) the name of the top level function called in his 
system, or 2) the name of a variable that evaluates to a list of top level 
functions, or 3) the list itself. All of the functions below each top level 
function will be analyzed, except those which are declared to bo 
"uninteresting," as described below. Note that after interscope goes into 
question-answering mode, the user can instruct interscope to analyze 
additional functions, either in English input, e.g. "ANALYZE FOOFNS." or by 
calling the function looka't directly (page 20.16). 

The structure of interscope may be divided into three major subsystems: a 

top-level monitor function, an English preprocessor, and the functions which 

build and search the data base. The monitor function is implemented via 

userexec (see Section 22), so that the features of the programmer's assistant 

ft 

are available from within interscope . For example, the user can REDO or FIX 
interscope questions, interrogate the history list for his session, or run 



When interscope is first called, and it has not previously analyzed any 
functions, it is in analysis mode, as indicated by its greeting and prompt 
character (&«- instead of 6c) (see [1] in Figure 20-3). Interscope goes into 
question-answering mode when the user answers NO to the question "Shall I 
analyse a (another) system?" ([2] in Figure 20-3). The only difference 
between analysis mode and question-answering mode is that in analysis mode, 
interscope treats forms as indicating a list of functions to be analysed, 
whereas in question-answering mode, interscope simply passes forms back to 
lispx for evaluation. 



interscope assumes that any input line terminated by a punctuation mark is 
intended for it to process, interscope will also attempt to process other 
input lines, i.e. those not ending in punctuation. However, if it is not 
able to make sense of the input, interscope will assume that it was 
intended to be handled by lispx , and pass it back for evaluation. For 
example, if the user types "HAS THOU SLAIN THE JABBERWOCK?" , intersco pe 
will respond "I didn't understand that", but if the user omits the '?', the 
line will be given to lispx for evaluation and (probably) cause a 
U.D.F . HAS error. 
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programs from within interscope . 



The English preprocessor translates English questions, statements, and 
commands into INTERLISP forms appropriate for searching and building the 
interscope data base. Although this preprocessor is fairly flexible and 
robust (e.g. includes spelling correction), it translates only a limited subset 
of English sentences, and replies M I didn't understand that." to anything 
outside this subset ([3] in Figure 20-3).^ When this happens, usually a simple 
rephrasing of the question will suffice to allow interscope to handle it ([4] 
in Figure 20-3) . 

The interscope data-base can be accessed directly by the user via the functions 
described below. It should be noted that interscope actually creates two data 
bases, the first containing information about the elementary relations between 
the functions and variables in the user's system, and the second containing 
information derived from the first, i.e. the paths by which one function calls 
another. The first data base is created when interscope analyzes a system (via 
the function lookat ) . The second data base is developed incrementally (by the 
function paths ) , depending on the questions asked by the user. Both data bases 
are stored on the property lists of the functions and variables which are 
analyzed. 



Since the data base that interscope constructs is global (stored on 
property lists), the user can also exit from interscope , either by typing 
OK or GOODBYE, or via control-D, and then reenter interscope at some lator 
point and continue asking questions, without having to reanalyze his 
functions. 



The translation of the most recent input is always stored in the function 
definition cell of the atom MEANING . 



Where possible, interscope will try to inform the user what part of the 
sentence it did not understand. 
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Interscope "understands" a wide variety of the elementary relations that exist 
between functions and variables, e.g. which functions bind, use, change, test, 
or smash a given variable, which functions may cause a given function to be 
called, either directly or indirectly,**^ which variables are used as global or 
local free variables, either by a given function or by a group of functions, 
etc . 

Information about the function-call paths from one program to another is 
"generalized" when it is stored; e.g. at [5] in Figure 20-3, one of the paths 
by which CLISPATOM calls LISTP is given as (CLISPATOM *** RETDWIH LISTP), 
which means that there is more than one path from CLISPATOM to RETDWIM, and 
more than one path from RETDWIH to LISTP. 

The conventions used by interscope for recognizing functions that are 
"uninteresting" are the same as those used by printstructure (page 20.3), i.e. 
yesfns , nofns f irstfn , and lastfn all have the same effect as for 
printstructure . 

Interscope Functions 

paths[x;y ; type ;must; avoid; only] Value is a list of paths from x to where 

each path is an ordered list of functions. is 
used to indicate multiple paths. For example, if 
FOO calls FIE, and FIE calls FUM directly as well 
as calling FIE1 which calls FUM, then 
paths[F00;FUM] returns ((FOO FIE *** FUM)). 



e.g. if FOO calls FIE, and FIE calls FUM, then FOO calls FUM indirectly. 
' SOMEHOW means directly or indirectly, e.g. 

"WHAT FUNCTIONS CALL FOO SOMEHOW?" 
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type , must, avoid ,, and only are optional, typo can 
be either CALLS or CALLEDBY (NIL is equivalent to 
CALLS), e.g. in the above example, 
paths[ FUM ;FOO; CALLEDBY] would return the same set 
of paths as paths[FOO;FUH] 9 except each path would 
be in the reverse order. 

must , avoid , and only are used to select out 
certain types of paths. Each can be specified by 
an atom which evaluates to a list of functions, or 
a form which evaluates to such a list. If (the 
value of) must is non-NIL, each path is required 
to go through at least one of the members of must . 
If avoid is non-MIL 9 no path can go through any 
member of avoid . If only is non-NIL* no path can 
go through any function which is not a member of 
only , i.e. each path can only go through functions 
on only J 1 

treepaths[x;y ; type ;must ;avoid;only] Like paths , except prints paths as a 

tree structure, as shown at [6] in Figure 20-3 , 
type , must , avoid , and only have the same meaning 
as with paths. 12 



11 



12 



paths is called for English inputs of the form: 
"WHAT ARE THE PATHS FROM x TO y?". Such questions can be modified with 
subordinate clauses to indicate values for must , avoid, and/or only, e.g. 
"WHAT ARE THE PATHS FROM F00 TO FIE WHICH ONLY GO THROUGH FOOFNS AND AVOID 
FIEFNS?" 

treepaths is called for English inputs of the form "SHOW ME HOW x CALLS y", 
" DISPLAY THE PATHS FROM x TO y\ etc. 
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lookat[x] Builds the initial data base describing the system 

x, where x is either the name of a function, the 
name of a variable which evaluates to a list of 
functions, or the list of functions itself, 

clumpget[ object ; relation; universe ] Value is a list of objects (functions or 

variables) which have the indicated relation with 
respect to object , e.g. clumpget [ F00; CALLERS ] 
returns a list of functions that call FOO, 
clumpget[X;SMASHERS] a list of functions that 
smash the variable X, etc, A complete list of the 
possible values for relation is given below. * 3 



object can be a list of objects (or a variable 
which evaluates to a list of objects) , in which 
case the value returned by clunpget is the list of 
all objects which have the indicated relation to 
any of the members of object . 

Similarly/ universe can be a list of objects (or a 
variable which evaluates to a list of objects), in 
which case the value returned by clumpget is the 
list of all objects in universe which have the 
indicated relation to object (or any of the 
members of object ) , e.g. 

clumpgett X;SMASHERS ; FOOFNS ] . 



If clumpget is given a value for relation that it does not recognize , it 
will attempt spelling correction, and if that fails, generate an error. If 
given a value for object that it has not seen before, it will type "I don't 
know anything about object, shall I analyse a system?" and go into analysis 
mode . 
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Finally,, universe can be a relation, which is 
equivalent to supplying clumpget[ object ;univorso ] 
in place of object , i.e. the value returned is tho 
list of all objects which have the indicatod 
relation to any of the members of the {set of all 
objects which bear the relationship universe to 
object } . For example, 

clumpget[FOO ; CALLERS ; CALLEDFNS ] is a list of all 
functions that call any of the functions (CALLERS) 
that are directly called by F00 (CALLEDFNS). 
clumpget[FOO;FREEUSERS;LOCALVARS] is a list of 
functions that use freely any of the variables 
that are bound locally by FOQ. 



Currently, the following relations are implemented: 

CALLERS list of functions that directly call object . 

CALLEDFNS list of functions directly called by object . 

CALLCAUSERS list of functions that call object , perhaps 

indirectly. In English: "WHO CALLS F00 SOMEHOW?". 



CALLSCAUSED list of functions called by object , perhaps 

indirectly. In English: "WHO OOES FOO CALL 
SOMEHOW?" 



ABOVE union of object with CALLCAUSERS , 

8ELOW union of object with CALLSCAUSED. 

ARGS arguments of object . 
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ARGBINDERS 



list of functions that have object as an argument. 



LOCALVARS 



list of variables that are locally bound in 
object , e.g. PROG vars. 



LOCALBINDERS 



list of functions that bind object as a local 
variable . 



FREEVARS 



list of variables used freely by object 



FREEUSERS 



list of functions that use object freely. 



LOCALFREEVARS 



list of variables that are used freely in object ,, 
but are bound in object before they are used, e.g. 
c lumpge t[ F00 ; LOCALFREEVARS ; BELOW ] gives a list of 
those variables used freely below F00, but are 
bound above the place that they are used. 14 In 
English: "WHAT ARE THE LOCAL FREE VARS (VARIABLES) 
BELOW F00?" 



GLOBALFREEVARS 



list of variables used freely in object without 
previously being bound in object . 



ENTRYFNS 



list of each function in object which is not 
called by any function in object other than 
itself, e.g. c lumpge t[FOOFNS ; ENTRYFNS ] . 



Note that if object is the name of a function and universe is NIL, 
LOCALFREEVARS will always be NIL, and GLOBALFREEVARS the same as FREEVARS . 
It is only in connection with collections of functions that LOCALFREEVARS 
and GLOBALFREEVARS become interesting. 
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SELFRECURSIVE 



list of functions in object which call themselves 
directly. 



CAUSESELFCALL list of functions in object which could call 

themselves, perhaps indirectly. 

CAUSERECURS10N list of functions in object which cause some 

function to call itself, perhaps indirectly. 

CHANGEVARS list of variables that are changed by object , 

where "changed 1 means any flavor of assignment, 
i.e. via SETQ, SETQQ, RPAQ, SETN, or even an 
expression of the form (RPLACA (QUOTE atom) value) 
(or FRPLACA. /RPLACA, SAVESET, etc.) 16 

CHANGERS list of functions that change object . 

Motet 'set' in English input means any flavor of assignment, and translates the 
same as * change' . 

SMASHVARS list of variables whose value are smashed by 

object , where 'smash' means the variable appears 
as the first argument to one of the list of 
functions on smasherslst . 



clumpget will accept as relations SETQVARS, SETQERS, SETVARS, SETTERS , 

SETOOERS, SETQQVARS, etc., in case the user wants to distinguish between 

the various flavors of assignments. In English, "WHAT ARE THE SETQERS OF 
X?", etc. 



Initially (RPLACA RPLACD FRPLACA FRPLACO /RPLACA /RPLACO NCONC NCONC1 
/NCONC /NC0NC1 ATTACH /ATTACH RPLNOOE /RPLNODE RPLNODE2 /RPLNODE2). As 
with assignments, clumpget will accept as relations RPLACAERS, RPLACAVARS. 
RPLACDERS, RPLACDVAR5, etc., in case the user wants to distinguish the 
different types of smashing. 
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list of functions that smash object . 



list of variables that are tested by object » where 
'tested' means they appear as the first argument 
to one of the list of functions on testerslst , 
initially (ATOM LISTP NUMBERP NLISTP STRINGP EO 
EQP EQUAL NULL) , or anywhere in an AND or OR, or 
as the predicate in a COMO clause, or as the first 
argument to SELECTQ, etc. 

list of functions that test object . 

list of variables that are used in object , where 
'used 1 means actually appear in the body of the 
function, i.e. if a variable is simply bound, but 
not actually used anywhere, it will not be 
included in the value of USEVARS. CHAN6EVARS and 
TESTVARS are subsets of USEVARS. 

list of functions that use object . 
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20 . 3 Helpsys 1 ' + 

Helpsys provides yet another form of on-line assistance to the user, namely in + 

the area of documentation of INTERLISP , Helpsys uses the INTERLISP Reference * 

Manual as a data base, and answers simple questions about INTERLISP by ♦ 

presenting the appropriate passages from the manual. Inquiries are made in the * 

form of simple sentences, void of punctuation,, terminated with a ♦ 

carriage-return. The following sample session illustrates the use of Helpsys . + 

User inputs are underlined. * 



«- HELPSYS] «• 

Type ??? <CR> for assistance ♦ 

! TELL ME ABOUT WHILE J * 

... WHILE as a CLISP Iterative statement operator from section 23 ♦ 

WHILE pred * 

provides a way of terminating the i.s. WHILE pred evaluates «• 

pred before each iteration, and if the value is MIL, exits. «• 

? TELL ME ABOUT EVAL;* * 

Do you want to see the function ? No + 

Do you want to see the break command ? Yes + 

EVAL ^ * 

Sane as 60 or OK except that the break is maintained after the + 

evaluation. The user can then Interrogate the value of the break * 

v/hich is bound on the variable lvalue, and continue with the break. * 

More? Yes ♦ 

Typing GO or OK following EVAL will not cause reevaluation but «■ 

another EVAL will. EVAL is a useful command when the user 1s not + 

sure whether or not the break will produce the correct value and. * 

wishes to be able to do something about it if it is wrong. * 

! TELL ME ABOUT UBj> * 

... UB as a break command from section 15 ♦ 

UB * 

unbreaks brkfn, e.g. «■ 

(FOO BROKEN) ♦ 

:UB * 

FOO ♦ 

: * 

and FOO is now unbroken ♦ 

JREDOEVAL2 ♦ 



Helpsys was written by R. L. Walker II. 4 
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Do you want to see the function ? /..yes 

eval[x] 

eval evaluates the expression x and returns this value I.e. 
eval provides a way of calling the interpreter. 
Footnote [7] now? Yes 



{ *7* } eval is a subr so that the 'name 1 x does not actually appear 

on the stack. 



Note that eval is itself a lambda type function, so its argument 

is the first evaluated, e.g. . {user aborts output by typing control~E) 

I WHAT ARE THE ARGS FOR BREAjOj 

Valid arguments for BREAK! are: [ BRKEXP ; BRKWHEN ;BRKFN ;BRKC0MS ; BRKTYPE ] 

8 TELL ME AOUT THE THIRD ARG FOR BREAKS 
=ABOUT 

... BREAK1 as a function from section 15 

break 1 [ brkexp ;brkwhen ;brkfn ;brkcoms;brktype] 

is an nlambda. brktype is MIL for user breaks, INTERRUPT for 
control-H breaks, and ERRORX for error breaks. 

! TELL ME ABOUT ERROR IN ARRAYSIZE^ 

... ARRAYSIZE as a function from section 10 

Generates an error, ARG NOT ARRAY, if a is not an array. 

! TELL ME ABOUT THE LAST ARUGNEMT OF CHANGEPROP,* 
^ARGUMENT 

... CHANGEPROP as a function from section 7 

changeprop[x ;propl ;prop2] 

Changes name of property propl to prop2 on property list of x, 
(but does not affect the value of the property). 

i USE 2ND FOR LAST,? 

... CHANGEPROP as a function from section 7 

changeprop[x ; propl ;prop2 ] 

Changes name of property propl to prop2 on property list of x, 
(but does not affect the value of the property). Value is x, 
(but does not affect the value of the property). 

! WHAT IS THE VALUE OF JMAPCj 

... MAPC as a function from section 11 

The value of mapc is NIL. 
f QtQ 
NIL 



The user could also interrupt the output by striking the 'del 1 key, which 
simply causes helpsys to skip over what it was currently typing, e.g. 
footnote, paragraph, etc., and continue with the same subject further on. 
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SECTION 21 
MISCELLANEOUS^ 

21.1 Measuring Functions 

time[ timex;timen;timetyp] is an nlambda function. It executes the 

computation t imex , and prints out the number of 
conses and computation time. Garbage collection 
time is subtracted out. 

«-TIME( ( LOAD (QUOTE PRETTY) (QUOTE PROP] 
FILE CREATED 7-HAY-71 12:47:14 

GC: 8 

582, 10291 FREE WORDS 

PRETTYFNS 

PRETTYVARS 

3727 CONSES 

10.655 SECONDS 

PRETTY 

If timen is greater than 1 ( timen ^NIL equivalent 
to timen =l ) , time executes timex timen number of 
times and prints out number of conses/timen , and 
computation time/timen. This is useful for more 
accurate measurement on small computations, e.g. 



Some of the functions in this section are TENEX or implementation 
dependent. They may not be provided in other implementations of INTERLISP . 



-TIME((COPY (QUOTE (A B C))) 10) 
30/10 = 3 CONSES 
.055/10 ■ .0055 SECONOS 
(A B C) 



If tlmetype is 0, time measures and prints total 
real time as well as computation time, e.g. 



-TIME((LOAD (QUOTE PRETTY) (QUOTE PROP)) 10] 
FILE CREATED 7-MAY-71 12:47:14 

GC: 8 

582, 10291 FREE WORDS 

PRETTYFNS 

PRETTYVARS 

3727 CONSES 

11.193 SECONDS 

27.378 SECONDS, REAL TIME 

PRETTY 



If timetyp = 3, time measures and prints garbage 
collection time as well as computation time, e.g. 



«-TIME( ( LOAD (QUOTE PRETTY) (QUOTE PROP) ) 1 3] 
FILE CREATED 7-MAY-71 12:47:14 



GC: 8 

582, 1091 FREE WORDS 
PRETTYFNS 
PRETTYVARS 
3727 CONSES 
10.597 SECONDS 

1.487 SECONDS, GARBAGE COLLECTION TIME 
PRETTY 



Another option is timetype =T, in which case time 
measures and prints the number of pagefaults. 



The value of time is the value of the last 



evaluation of tlmex. 
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date[ ] obtains date and time, returning it as single string in 

format "dd-m-yy hh:mm:ss { \ where dd is day, nun is 
month, yy year, hh hours p mm minutes, ss seconds, 
e.g., "14-MAY-71 14:26:08". 



clock[n] for nsO 



for n~i 



for ns2 



for ns3 



current value of the time of day clock 
i.e., number of milliseconds since last 
system start up. 

value of the time of day clock when the 
user started up this INTERLISP, i.e., 
difference between clock[0] and clock[l] 
is number of milliseconds (real time) 
since this 1NTERLISP was started. 

number of milliseconds, of compute time 
since user started up this 1MTERL ISP 
(garbage collection time is subtracted 
off). 

number of milliseconds ' of compute time 
spent in garbage collections (all 
types ) 



dismiss[n] In INTERLISP--10., dismisses program for n 



In INTERLISP-10, date will accept a value for ac3 as an argument. ac3 can 
be used to specify other formats, e.g. day of week, time zone, etc., as 
described in TENEX JSVS manual. 



In INTERLISP-10, this number is directly accessible via the COREVAL GCTXM, 



milliseconds, during which time program is in a 
state similar to an I/O wait, i.e., it uses no CPU 
time. Can be aborted by control-D, control-E, or 
control-B. 



conscount[n] 



conscount[ ] returns the number of conses since 
INTERLISP started up. If n is not NIL, resets 
conscount to n . 



boxcoun t[ type ; n ] 



In INTERLISP-10, number of boxing operations (seo 
Section 13) since INTERLISP started up. If 
type =NIL, returns number of large integer boxes; 
typesFLOATING, returns number of floating boxes. 4 
If n is not NIL, resets the corresponding counter 
to n . 



gctrp[ ] 



number of conses to next GC: 8, i.e., number of 
list words not in use. Note that an intervening 
GC of another type could collect as well as 
allocate additional list words. See Section 3. 



gctrp[n] can be used to cause an interrupt when 
value of gctrp[ ]=n , see Section 10 . 



pagefaults[ ] 



In INTERLISP- 10 , number of page faults since 
INTERLISP started up. 



In INTERLISP-10, these counters are directly accessible via the COREVALs 
IBOXCN and FBOXCN. 
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logout[] returns control to operating system. In 

INTERLISP-10, a subsequent CONTINUE command will 
enter the INTERLISP-10 program, return MIL as tho 
value of the call to logout , and continue tho 
computation exactly as if nothing had happened, 
i.e., logout is a programmable control-C. As with 
control-C, a REENTER command following a logout 
will reenter INTERLISP-10 at the top level. 

logout[] will not affect the state of any open 
files. 

21 .2 Breakdown^ 



Tine gives analyses by computation. Breakdown is available to analyze the 
breakdown of computation time (or any other measureable quantity) function by 
function. The user calls breakdown giving it a list of functions of interest. 
These functions are modified so that they keep track of the "charge" assessed 
to them. The function results gives the analysis of the statistic requested as 
well as the number of calls to each function. Sample output is shown below. 



In INTERLISP-10 , if INTERLISP was started as a subsidiary fork (see subsys, 
page 21 .19), control is returned to the higher fork. 

breakdown was written by W. Teitelman. 
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-BREAKDOUN(SUPERPRINT SUBPRINT COMMENT 1) 
(SUPERPRINT SUBPRINT COMMENT 1 ) 
*-PRETTYDEF( (SUPERPRINT) FOO) 
FOO. ;3 
-RESULTS* ) 



FUNCTIONS 


TIME 


# CALLS 


PER CALL 


'A 


SUPERPRINT 


8.261 


365 


0.023 


20 


SUBPRINT 


31.910 


141 


0,226 


76 


COMMENT1 


1.612 


8 


0.201 


4 


TOTAL 


41.783 


514 


0.081 





NIL 



The procedure used for measuring is such that if one function calls other and 
both are 'broken down 1 , then the time (or whatever quantity is being measured) 

7 

spent in the inner function is not charged to the outer function as well. 

To remove functions from those being monitored, simply unbreak the functions, 
thereby restoring them to their original state. To add functions, call 
breakdown on the new functions. This will not reset the counters for any 
functions not on the new list. However breakdown[ ] can be used for zeroing the 
counters of all functions being monitored. 

To use breakdown for some other statistic, before calling breakdown , set the 
variable brkdwntype to the quantity of interest, e.g., TIME, CONSES, etc. 
Whenever breakdown is called with brkdwntype not NIL, breakdown performs the 
necessary changes to its internal state to conform to the new analysis. In 
particular, if this is the first time an analysis is being run with this 
statistic, the compiler may be called to compile the measuring function. ^ When 
breakdown is through initializing, it sets brkdwntype back to NIL. Subsequent 



breakdown will not give accurate results if a function being measured is 
not returned from normally, e.g. a lower retf rom (or error ) bypasses it. 
In this case, all of the time (or whatever quantity is being measured) 
betv/een the time that function is entered and the time the next function 
being measured is entered will be charged to the first function. 

The measuring functions for TIME and CONSES have already been compiled. 
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calls to breakdown will measure the new statistic until brkdwntype is again sot 
and a new breakdown performed. Sample output is shown below: 



«-SET( BRKDWNTYPE CONSES) 
CONSES 

♦-BREAKDOWN (MATCH CONSTRUCT) 
(MATCH CONSTRUCT) 



<-FLIP( ( A B 


C D E F G H 


C Z) (.. 


$1 . . 42 . 


. ) ( • 


(A B D E F 


GHZ) 








~RESULTS( ) 










FUNCTIONS 


CONSES 


# CALLS 


PER CALL 


% 


MATCH 


32 


1 


32.000 


41 


CONSTRUCT 


47 


1 


47.000 


59 


TOTAL 


79 


2 


39.500 





NIL 



The value of brkdwntype is used to search the list brkdwntypes for the 
information necessary to analyze this statistic. The entry on brkdwntypos 
corresponding to brkdwntype should be of the form (type form function), whore 
form computes the statistic P and function (optional) converts the value of form 
to some more interesting quantity, e.g. 

(TIME (CLOCK 2) (LAMBDA (X) (FQUOTIENT X 1000 ))) 9 measures computation time and 
reports the result in seconds instead of milliseconds. If brkdwntype is not 
defined on brkdwntypes , an error is generated, brkdwntypes currently contains 
entries for TIME, CONSES, PAGEFAULTS, BOXES, and FBOXES. 



More Accurate Measurement 



Occasionally, a function being analysed is sufficiently fast that the overhead 
involved in measuring it obscures the actual time spent in the function. If 
the user were using time , he would specify a value for timen greater than 1 to 
give greater accuracy. A similar option is available for breakdown. The user 



For more accurate measurement , the form for TIME in lNTERLlSP-10 is not 
(CLOCK 2) but (ASSEMBLE NIL (JSYS 206) (SUB 1 , GCTIM) ) . 
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can specify that a function(s) be executed a multiple number of times for each 
measurement, and the average value reported, by including a number in the list 
of functions given to breakdown , e.g., BREAKDOWN EDXTCOM EDIT4F 10 EDIT4E EQP) 
means normal breakdown for editcom and edit4f but executes (the body of) cdit4e 
and eqp 10 times each time they are called. Of course, the functions so 
measured must not cause any harmful side effects, since they are executed more 
than once for each call. The printout from results will look the same as 
though each function were run only once, except that the measurement will be 
more accurate . 

21.3 Edita iQ 

Edita is an editor for arrays. However* its most frequent application is in 
editing compiled functions (which are also arrays in INTERLISP-10 ) , and a great 
deal of effort in implementing edita , and most of its special features, are in 
this area. For example, edita knows the format and conventions of INTERLISP-10 
compiled code, and so, in addition to decoding instructions a la DDT, 1 1 edita 
can fill in the appropriate COREVALS, symbolic names for index registers, 
references to literals, linked function calls, etc. The following output shows 
a sequence of instructions in a compiled function first as they would be 
printed by DDT, and second by edita . 



edita was written by W. Teitelman, and modified by D. C. Lewis. That 
portion of edita relating to compiled code may or may not be available in 
implementations of INTERLISP other than INTERLISP-10 . 



DDT is one of the oldest debugging systems still around. For users 
unfamiliar with it, let us simply say that edita was patterned after it 
because so many people are familiar with it. 
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466716/ 
466717/ 
466720/ 
466721/ 
466722/ 
466723/ 
466724/ 
466725/ 
466726/ 
466727/ 
466730/ 
466731/ 
466732/ 
466733/ 
466734/ 
466735/ 
466736/ 
466737/ 
466740/ 
466741/ 
466742/ 
466743/ 



PUSH 16.1ISP&KNIL. 
PUSH 16.LISP&KNII 
HRRZ 1.-12(16) 
CAME l.LISP&KNIL 
JRST 466724 
HRRZ 1,0467575 
PUSH 16,1 

LISP&IOFIL, ,467576 
-3 -3 

HRRZ 1,-14(16) 
CAMN 1,467601 
JRST 466734 
CAME 1,467602 
JRST 466740 
PUSH 16,467603 
PUSH 16,467604 
LISP&FILEN, ,467605 
JRST 467561 
CAME 1.467606 
JRST 466754 
HRRZ 1,G>-12(16) 
PUSH 16,1 



3/ 

4/ 

5/ 

6/ 

7/ 

8/ 

9/ 

10/ 

11/ 

12/ 

13/ 

14/ 

15/ 

16/ 

17/ 

18/ 

19/ 

20/ 

21/ 

22/ 

23/ 

24/ 



PUSH PP.KNIL 
PUSH PP.KNIL 
HRRZ 1,-10(PP) 
CAME l.KNIL 10 
JRST 9 ld 
HRRZ 1,0' BRKFILE 
PUSH PP,1 
PBIND 'BRKZ 
-524291 

HRRZ 1,-12(PP) 
CAMN 1, 'OK 
JRST 17 
CAME 1, 'STOP 
JRST 21 

PUSH PP, ' BREAK 1 
PUSH PP, '(ERROR! ) 
CCALL 2 , ' RETEVAL 
JRST 422 
CAME 1, 'GO 
JRST 33 

HRRZ 1,@-10(PP) 
PUSH PP. 1 



Therefore, rather than presenting edlta as an array editor with some extensions 
for editing compiled code, we prefer to consider it as a facility for editing 
compiled code, and point out that it can also be used for editing arbitrary 
arrays . 



To the user, edita looks very much like DDT with INTERLISP-10 extensions. It 
is a function of one argument, the name of the function to. be edited. 
Individual registers or cells in the function may be examined by typing their 
address followed by a slash, 24 e.g. 



Note that edita prints the addresses of cells contained in the function 
relative to the origin of the function. 



An optional second argument can be a list of commands for edita . These are 
then executed exactly as though they had come from the teletype. 



Underlined characters were typed by the user. edita uses its own read 
program, so that it is unnecessary to type a space before the slash or to 
type a carriage return after the slash. 



Overview 
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6/ HRRZ 1,-10(PP) 



The slash is really a command to edita to open the indicated register. Only 
one register at a time can be open, and only open registers can be changed . To 
change the contents of a register, the user first opens it, types the new 
contents, and then closes the register with a carriage-return, 16 e.g. 

77 CAME 1 , ' t CAMN 1, 'Q 

If the user closes a register without specifying the new contents, the contents 
are left unchanged. Similarly, if an error occurs or the user types control-E, 
the open register, if any, is closed without being changed. 

Input Protocol 

Edita processes all inputs not recognized as commands in the same way. If the 
input is the name of an instruction (i.e. an atom with a numeric OPD property), 
the corresponding number is added to the input value being assembled, and a 
flag is set which specifies that the input context is that of an instruction. 

The general form of a machine instruction is (opcode ac , 0 address (index)) as 
described in Section 18. Therefore, in instruction context, edita evaluates 
all atoms (if the atom has a COREVAL property, the value of the COREVAL is 



edita also converts absolute addresses of cells within the function to 
relative address on input. Thus, if the definition of foo begins at 85060, 
typing 6/ is exactly the same as typing 85666/. 



Since carriage-return has a special meaning, edita indicates the balancing 
of parentheses by typing a space. — — 

The input value is initially 0. 
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used), and then if the atom corresponds to an ac, shifts it left 23 bits and 
adds it to the input value, otherwise adds it directly to the input value, but 
performs the arithmetic in the low 18 bits.* 9 Lists are interpreted as 
specifying index registers, and the value of car of the list (again COREVALs 
are permitted) is shifted left 18 bits. Examples: 

PUSH PP, KNIL 
HRRZ 1,-10(PP) 
CAME 1, 'GO 
JRST 33 ORG dU 

The user can also specify the address of a literal via the 1 command, see page 
21.14. For example, if the literal " UNBROKEN" is in cell 85672, 
HRRZ 1,'" UNBROKEN" is equivalent to HRRZ 1, 85672. 

When the input context is not that of an instruction, i.e. no OPD has boon 
seen, all inputs are evaluated (the value of an atom with a COREVAL property is 
the COREVAL . ) Then numeric values are simply added to the previous input value; 

21 ' 

non-numeric values become the input value. 

The only exception to the entire procedure occurs when a register is open that 
is in the pointer region of the function, i.e. literal table. In this case, 



18 



19 



20 



21 



i.e. if a has not been seen, and the value of the atom is less than 16, 
and the low 18 bits of the input value are all zero. 

If the absolute value of the atom is greater than 1000000Q, full word 
arithmetic is used. For example, the indirect bit is handled by simply 
binding @ to 20000000Q. 

edita cannot in general know whether an address field in an instruction 
that is typed in is relative or absolute. Therefore, the user must add 
ORG, the origin of the function, to the address field himself. Note that 
edita would print this instruction, JRST 53 ORG, as ORST 53. 

Presumably there is only one input in this case. 
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atomic inputs are not evaluated. For example, the user can change the literal 
FOO to FIE by simply opening that register and then typing FIE followed by 
carriage-return, e .g. 

'FOO/ FOO FJEj 
Note that this is equivalent to 'FOO/ FOO (QUOTE FIE),) 

Edita Commands and Variables 

} (carriage-return) If a register is open and an input was typed, 

store the input in the register and close it. 

If a register is open and nothing was typed, close 
the register without changing it. 

If a register is not open and input was typed, 
type its value. 



ORG Has the value of the address of the first 

instruction in the function, i.e. loc of getd of 
the function. 



/ Opens the register specified by the low 18 bits of 

the quantity to the left of the /, and types its 
contents. If nothing has been typed, it uses the 
last thing typed by edita , e.g. 



35/ JRST 53 / CAME 1 , 'RETURN / RETURN 



If a register was open, / closes it without 
changing its contents. 

After a / command, edita returns to that state of 
no input having been typed. 

tab (control- 1) Same as carriage-return, followed by the address 

of the quantity to the left of the tab, e.g. 

35/ JRST 53 tab 



22 

If the register is in the unboxed region of the function, the unboxed value 
is stored in the register. 
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53/ CAME 1, 1 RETURN 



Note that if a register was open and input was typed, tab will change the open 
register before closing it, e.g. 



35/ JRST 53 JRST 54 tab 
54/ JRST 70 2 
35/ JRST 54 



( period) 



has the value of the address of the current (last) 
register examined. 



line-feed 



same as carriage-return followed by (ADD1 .)/ i.e. 
closes any open register and opens the next 
register. 



same as carriage-return followed by (SUB1 .)/ 



SQ (alt-modeQ) 



has as its value the last quantity typed by edita 
e.g. 



35/ JRST 53 SO Q 
./ JRST 54 



LITS 



has as value the (relative) address of the first 
literal. 



BOXED 

S (dollar) 



same as LITS 



has as value the relative address of the last 
literal in the function. 



Sets radix to -8 and types the quantity to the 

left of the = sign, i.e. if anything has boon 

typed, types the input value, otherwise, types SQ, 
e.g. 



35/ JRST 54 =2540002415410 JRST 54 = 2540000000660 



Following =, radix is restored and edita returns 
to the no input state. 



OK 
? 



leave edita 



return to *no input' state. ? is a 'weak* 
control-E, i.e. it negates any input typed, but 
does not close any registers. 
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addressl, addressZ/ prints 23 the contents of registers address 1 

through addressZ . . is set to addressZ after the 
completion. 

'x corresponds to the 1 in LAP. The next expression 

is read, and if it is a small number, the 
appropriate offset is added to it. Otherwise, the 
literal table is searched for x» and the value of 
'x is the (absolute) address of that coll. An 
error is generated if the literal is not found, 
i.e. 1 cannot be used to create literals. 

:atom defines atom to an address 

(1) the value of SO if a register is open, 

(2) the input if any input was typed, 
otherwise Df 

(3) the value of ' . 1 « q 
For example: 

35/ JRST 54 ;F00^ 

FIE/ JRST F00 .=35 



Edita keeps its symbol tables on two free variables, uscrsyms and syrolst . 
Usersyms is a list of elements of the form (name , value) and is used for 
encoding input, i.e., all variables on usersyms are bound to their 
corresponding values during evaluation of any expression inside edita . Syrrtls t 
is a list of elements of the form (value . name) and is used for decoding 
addresses. Usersyms is initially NIL, while symlst is set to a list of all the 
corevals . Since the : command adds the appropriate information to both these 
two lists, new definitions will remain in effect even if the user exits from 
edita and then reenters it later. 

Note that the user can effectively define symbols without using the : command 



23 



24 



output goes to file , initially set to T. The user can also set file (while 
in edita ) to the name of a disc file to redirect the output. (The user is 
responsible for opening and closing file .) Note that file only affects 
output for the addressl, addressZ/ command. 

Only the low 18 bits are used and converted to a relative address whenever 
possible . 
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by appropriately binding users yros and/or synlst before calling edita . Also P ho 
can thus use different symbol tables for different applications. 

SW (alt-modeW) search command. 

Searching consists of comparing the object of the search with the contents of 
each register, and printing those that match, e.g. 

HRRZ g SW,> 

8/ HRRZ 1 ,© 'BRKFILE 
23/ HRRZ 1,@-10(PP) 
28/ HRRZ i f 9-12(PP) 

The SW command can be used to search either the unboxed portion of a function, 
i.e. instructions, or the pointer region, i.e. literals, depending on whether 
or not the object of the search is a number. If any input was typed before the 
SW, it will be the object of the search, otherwise the next expression is read 
and used as the object. The user can specify a starting point for the search 
by typing an address followed by a 8 , 1 before calling SW, e.g. 1 , JR5T SW. If 
no starting point is specified, the search will begin at 0 if the object is a 
number, otherwise at LITS, the address of the first literal. After the search 
is completed, ' . 1 is set to the address of the last register that matched. 

If the search is operating in the unboxed portion of the function, only those 
fields (i.e. instruction, ac, Indirect, index, and address) of the object that 
contain one bits are compared. 2J? for example, HRRZ 9 SW will find all instances 



Note that inputs typed before the SW will have been processed according to 
the input protocol, i.e. evaluated; inputs typed after the SW will not. 
Therefore, the latter form is usually used to specify searching the 
literals, e.g. SW F00 is equivalent to (QUOTE F00) SW. 



Thus the only way the user can search the pointer region for a number is to 
specify the starting point via 



Alternately, the user can specify his own mask by setting the variable mask 
(while in edita), to the appropriate bit pattern. 
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of HRRZ indirect, regardless of ac, index, and address fields. Similarly, 
•PRINT SW will find all instructions that reference the literal PRINT. 25 



If the search is operating in the pointer region, a 'match 1 is as defined in 
the editor. For example, SW (&) will find all registers that contain a list 
consisting of a single expression. 

SC (alt-modeC) like SW except only prints the first match, thon 

prints the number of matches when the search 
finishes. 

Editing Arrays 

Edita is called to edit a function by giving it the name of the function. 
Edita can also be called to edit an array by giving it the array as its first 
argument, ■ in which case the following differences are to be noted: 

1. decoding - The contents of registers in the unboxed region are boxed 
and printed as numbers, i.e. they are never interpreted as 
instructions, as when editing a function. 

2. addressing convention - Whereas 0 corresponds to the first instruction 
of a function, the first element of an array by convention is element 
number 1 . 



28 



29 



The user may need to establish instruction context for input without giving 
a specific instruction. For example, suppose the user wants to find all 
instructions with ac=l and index^PP. In this case, the user can give & as 
a pseudo-instruction, e.g. type & 1, (PP). 

the array itself, not a variable whose value is an array, e.g. (EDITA FOO) , 
not EDITA(FOO). 
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3. input protocols - If a register is open, lists are evaluated, atoms 
are not evaluated (except for $Q which is always evaluated). If no 
register is open, all inputs are evaluated, and if the value is a 
number, it is added to the 'input value 1 . 

4. left half - If the left half of an element in the pointer region of an 
array is not all O's or NIL, it is printed followed by a ; , e.g. 

10/ (A B) ; T 

Similarly, if a register is closed, either its left half, right half, 
or both halves can be changed, depending on the presence or absence, 
and position of the ; e.g. 



10/ 


(A B) ; T 


B; ) changes left 


J_ 


8 ; T 


NIL,? changes right 


J_ 


B ; NIL 


A ; C> changes both 


J_ 


A ; C 





If ; is used in the unboxed portion of an array, an error will bo 
generated. 

The SW command will look at both halves of elements in the pointer region, and 
match if either half matches. Note that SW A ; B is not allowed. 

This ends the section on edita. 



21.17 



21.4 Interfork Communication in INTERLISP-10 



The functions described below permit two forks (one or both of thorn 
IMTERLISP-10 ) to have a common area of address space for communication by 
providing a means of assigning a block of storage guaranteed not to move during 
garbage collections. 

getblk[n] Creates a block n pages in size (512 words per 

page). Value is the address of the first word in 
the block, which is a multiple of 512 since the 
block will always begin at a page boundary. If 
not enough pages are available, generates the 
error ILLEGAL OR IMPOSSIBLE BLOCK. 

Motei the block can be used for storing unboxed numbers onijj . 

To store a number in the block, the following function could be used: 

[SETBLOCK (LAMBDA (START N X) (CLOSER (IPLUS (LOC START) N) X] 

Some boxing and unboxing can be avoided by making this function compile open 
via a substitution macro. 

Note: getblk should be used sparingly since several unmovable regions oj -memory 
can make it difficult or impossible for the garbage collector to find a 
contiguous region large enough for expanding array space: 

relblk[address;n] releases a block of storage beginning at address 

and extending for n pages. Causes an error 
ILLEGAL OR IMPOSSIBLE BLOCK if any of the range is 
not a block. Value is address. 
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This section describes a function, subsys , which permits the user to run a 
TENEX subsystem, such as SNDNSG, SRCCOM, TECO, or even another INITERLISP, from 
inside of an INTERLISP without destroying the latter. In particular. 
SUBSYS(EXEC) will start up a lower exec, which will print the TENEX herald, 
followed by @. The user can then do anything at this. exec level that he can at 
the top level, without affecting his superior INITERLISP. For example, he can 
start another INTERLISP, perform a sysin , run for a while, type a control-C 
returning him to the lower exec, RESET, do a SNDMSG, etc. The user exits from 
the lower exec via the command QUIT, which will return control to subsys in the 
higher INTERLISP. Thus with subsys , the user need not perform a sysout to save 
the state of his INTERLISP in order to use a TENEX capability which would 
otherwise clobber the core image. Similarly, subsys provides a way of checking 
out a sysout file in a fresh INTERLISP without having to commandeer another 
teletype or detach a job. 

While subsys can be used to run any TENEX subsystem directly, without going 
through an intervening exec, this procedure is not recommended. The problem is 
that control-C always returns control to the next highest exec. Thus if the 
user is running an INTERLISP in which he performs SUBSYS( LISP) , and then typos 
control-C to the lower INTERLISP, control will be returned to the exec above 
the first INTERLISP. The natural REENTER command would then clear the lower 
INTERLISP, but any files opened by it would remain open (until the next 
0RESET). If the user elects to call a subsystem directly, he must therefore 



subsys was written by J.W. Goodwin. It is TENEX dependent and may not bo 
available in implementations of INTERLISP other than INTERLISP- 10 . 

A CONTINUE command however will return to the subordinate program, i.e. 
control-C followed by CONTINUE is safe at any level. 



21.19 



know how it is normally exited and always exit from it that way. 



Starting a lower exec does not have this disadvantage, since it can only bo 
exited via QUIT, i.e., the lower exec is effectively 'errorset protected' 
against control-C. 

subsys[ f ile/fork;incomfile;outcomfile;entrypointflg] 

If f ile/fork -EXEC, starts up a lower exec, 
otherwise runs <SUBSYS>system, e.g. 

subsys[SNDMSG]»subsys[TECO] etc. subsys[ ] is samo 
as subsys[EXEC]. Control-C always returns control 
to next higher exec. Not© that more than one 
IMTERLISP can be stacked, but there is no 
backtrace to help you figure out where you are. 

incomf ile and outcomf lie provide a way of 
specifying files for input and output, incomf lie 
can also be a string, in which case a temporary 
file is created, and the string printed on it. 

entrypolntflg may be START, REENTER, or CONTINUE. 
NIL is equivalent to START, except when file/fork 
is a handle (see below) in which case NIL is 
equivalent to CONTINUE. 

The value of subsys is a large integer which is a handle to the lower fork. 
The lower fork is not reset unless the user specifically does so using kfork , 



IMTERLISP is exited via the function logout , TECO via the command ;H, 
SNDMSG via control-Z, and EXEC via QUIT. 
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described below. * If subsys is given as its first argument the value of a 
previous call to subsys ,^, it continues the subsystem run by that call. For 
example, the user can do (SETQ SOURCES (SUBSYS TECO)), load up the TECO with a 
big source file, massage the file, leave TECO with ;H, run 1MTERLISP for awhile 
(possibly including other calls to subsys ) and then perform (SUBSYS SOURCES) to 
return to TECO, where he will find his file loaded and even the TECO pointer 
position preserved . 

Note that if the user starts a lower EXEC, in which he runs an INTERLISP, 
control-C's from the INTERLISP, then QUIT from the EXEC, if he subsequently 
continues this EXEC with subsys , he can reenter or continue the INTERLISP. 

Note, also that calls to subsys can be stacked. For example, using subsys , the 
user can run a lower INTERLISP, and within that INTERLISP, yet another, etc., 
and ascend the chain of INTERLISPs using logout , and then descend back down 
again using subsys . 

For convenience, subsys[T] continues the last subsystem run. 

SNDMSG, LISP, TECO, and EXEC, are all LISPXMACROS which perform the 
corresponding calls to subsys . CONTIN is a LISPXMACRO which performs 
subsys[T], thereby continuing the last subsys . 



The fork is also reset when the handle is no longer accessible, i.e., when 
nothing in the INTERLISP system points to it. Note that the fork is 
accessible while the handle remains on the history list. 



Must be the exact same large number, i.e. eg. Note that if the user 
neglects to set a variable to the value of a call to subsys » (and has 
performed an intervening call so that subsys[T] will not work), he can 
still continue this subsystem by obtaining the value of the call to subsys 
for the history list using the function valueof , described in Section 22. 
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kf ork[ fork] 



accepts a value from subsys and kills it (RESET in 
TEMEX terminology). If subsys[fork] is 
subsequently performed, an error is generated. 
kfork[T] kills all outstanding forks (from this 
INTERLISP). 



21 ,6 Miscellaneous Tenex Functions in INTERLISP-10 
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f ildir[ f ilegroup] 



f ilegroup is a TENEX file group descriptor, i.e., 
it can contain stars. f ildir returns a list of 
the files which match f ilegroup , a la the TEMEX 
DIRECTORY command, e.g. (FILDIR (QUOTE *. COM ;0)). 



loadav[ ] 



returns TEMEX current load average as a floating 
point number (this number is the first of the 
three printed by the TEMEX SYSTAT command). 



erstr[ern] ern is an error number from a JSYS fail return. 

ernsNIL means most recent error. erstr returns 

the TENEX error diagnostic as a string 
(from <SYSTEM>ERROR. MNEMONICS). 

jsys[n ;acl ;ac2;ac3;resultac] loads (unboxed) values of acj., ac2 , and ac3 

into appropriate accumulators, and executes TENEX 
JSYS number N. If act . ac2, or ac3=NIL, 0 is 
used. Value of jsys is the (boxed) contents of 
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All of the functions in section 21.5, except for tenex , were written by 
J.W. Goodwin. 
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the accumulator specified by resultac , i.e. 1 
means acl, 2 means ac2, and 3 moans ac3 , with NIL 
equivalent to 1. 

username[a] If a=NIL, returns login directory name; if a=T, 

returns connected directory name; if a is a 
number, username returns the user namo 
corresponding to that user number. In all cases, 
the value is a string. 

usernumber[a] If a-NIL, returns login user number; if a = T, 

returns connected user number; if a is a literal 
atom or string,- usernumber returns the number of 
the corresponding user, or NIL if no such user 
exists . 

Note: greeting (see Section 22) sets the variable username to the login user 
name, and f irstname to the name used in the greeting. 

tenex[str] Starts up a lower EXEC (without a message) using 

subsys , and then unreads str, followed by "QUIT" 
(using bksysbuf , described in Section 14). For 
example, the LISPXMACRO SY which does a SYSTAT is 
implemented simply as TENEX[ "SY> M ]. 

21.7 Printing Reentrant and Circular List Structures 

A reentrant list structure is one that contains more than one occurrence of the 
same (eg;) structure. For example, tconc (Section 6) makes uses of reentrant 
list structure so that it does not have to search for the end of the list each 
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time it is called. Thus, if x is a list of 3 elements, (A B C), being 
constructed by tconc, the reentrant list structure used by tconc for this 
purpose is: 



A 




E> 


B 














— ->j C 


V 



FIGURE 21-1 

This structure would be printed by print as ((A 6 C) C) ♦ Mote that print would 
produce the same output for the non-reentrant structure: 



f> C 



A 






B 






C 


/ 









— -|> 



FIGURE 21-2 

In other words, print does not indicate the fact that portions of the structure 
in Figure 21-1 are identical. Similarly, if print is applied to a circular 
list structure (a special type of reentrant structure) it will never terminate. 

For example, if print is called on the structure: 



FIGURE 21-3 

it will print an endless sequence of loft parentheses, and if applied to: 
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dE5 

FIGURE 21-4 

will print a left parenthesis followed by an endless sequence of A's. 

The function circlprint described below produces output that will exactly 

36 

describe the structure of any circular or reentrant list structure. This 
output may be in either single or double-line formats. Below are a few 
examples of the expressions that circlprint would produce to describe the 
structures discussed above. 



expression in Figure 21-1: 
single-line: ((A B *1* C) {1}) 
double-line: ((A B C) . {!>) 



expression in Figure 21-3: 

single-line: («1* {!}) 

double-line: ({1}) 
1 



expression in Figure 21-4: 

single-line: A . {1}) 

double -line: (A . {1}) 
1 
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Circlprint and circlmaker were written by P. C. Jackson. 
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The more complex structure: 









A 






B 










^ 




^ 



















FIGURE 21-5 

is printed as follows: 

single-line: (*2« («1* {1} «3« {2} A «4* B . {3}) . {4}) 

double-line: ( ({1} {2} A B . <3}) . {4}) 
2 13 4 

In both formats, the reentrant nodes in the list structure are labeled by 
numbers. (A reentrant node is one that has two or more pointers coming into 
it.) In the single-line format, the label is printed between asterisks at the 
beginning of the node (list or tail) that it identifies. In the double-line 
format, the label is printed below the beginning of the node it identifies. An 
occurrence of a reentrant node that has already been identified is indicated by 
printing its label in brackets. 



circlprint[ list ; print fig; rlknt] prints an expression describing list . If 

printf lg sNIL, double-line format is used, 
otherwise single-line format. circlprint first 
calls circlmarkC list ;rlknt], and then calls either 
rlprinl[list] or rlprin2[ list], depending on the 
value of printf lg (T or NIL, respectively), 

V 

Finally, rlrestore[list] is called, which restores 
list to its unmarked state. Value is list. 
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circlmark[list;rlknt] marks each reentrant node in list with a unique 

number, starting at rlknt +1 (or 1, if rlknt is 
NIL) . Value is (new) rlknt . 

Marking list physically alters it. However, the 
marking is performed undoably. In addition, list 
can always be restored by specifically calling 
rlrestore . 

rlprinl[ list ] prints an expression describing list in the 

single-line format. Does not restore list to its 
uncirclmarked state. list must previously have 
been clrclmarked or an error is generated. 

rlprin2[ list ] same as rlprinl , except that the expression 

describing list is printed in the double-line 
format. 

rlrestoreC list] physically restores list to its original, unmarked 

state. 

Mote that the user can mark and print several structures which together share 
common substructures, e.g. several property lists, by making several calls to 
circlmark , followed by calls to rlprinl or rlprin2 , and finally to rlrestore . 

circlmaker[ list] 1 1st may contain labels and references following 

the convention used by circlprint for printing 
reentrant structures in single line format, e.g. 
(*1* . {1}). circlmaker performs the necessary 
rplaca l s and rplacd 's to make list correspond to 
the indicated structure. Value is (altered) list . 
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circlmakerl[ list ] 



Does the work for circlnaker . Uses fro® variables 



labelst and reflst. 



labelst is a list of dotted 



pairs of labels and corresponding nodes. ref 1 st 



is a list of nodes containing references to labels 



not yet seen. Circlmaker operates by initializing 



labelst and reflst to NIL, and then calling 



circlmakerl . It generates an error if reflst is 



not MIL when circlmakerl returns. 



The user can 



call circlmakerl directly to "connect up" several 



structures that share common substructures, e.g. 



several property lists. 



Dumping Unusual Data Structures 

The circlprint package is designed primarily for displaying complex list 
structures, i.e. printing them so that the user can look at them (although 
circlmaker can be used in conjunction with read for dumping and reloading 
re-entrant list structures). Hprint 0 is a package for printing and reading 
back in. more general data structures that cannot normally be dumped and loaclod 
easily, e.g., (possibly re-entrant or circular) structures containing user 
datatypes, arrays, hash tables, as well as list structures. 0 * 5 Hprint will 
correctly print and read back in any structure containing any or all of the 
above, chasing all pointers down to the level of atoms, numbersor strings. 

Hprint operates by simulating the INTERLISP print routine for normal list 
structures. When it encounters a user datatype (see section 23), or an array 

• • f - - - - - - mm m m mm mm.mm mmmmm~mmm*mmmmmmmmmmmmmmmm*,mm»,mm«>mm*. a mmmmmmm<mmmmmmmm*, 

for Horrible PRINT . The hprint package was written by L. M. Masinter. 

Hprint currently cannot handle compiled code arrays, stack positions, or 
arbitrary unboxed numbers. 
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or hash array, it prints the data contained therein, surrounded by special + 

characters defined as read-macro characters (see section 14). While chasing *■ 

the pointers of a list structure, it also keeps a hash table of those items it * 

encounters, and if any item is encountered a second time, another read-macro * 

character is inserted before the first occurrence, 3 ^ and all subsequent «> 

occurrences are printed as a back reference using an appropriate macro ^ 

character. Thus the inverse function, hread merely calls the INTERLISP road * 

routine with the appropriate readtable, so that reading time is only a function ♦ 

of the complexity of the structure. •> 

hprint[x;f ile] prints x on file . 40 ♦ 

hread[file] reads an hprint-ed expression from file . ♦ 

HORRIBLEVARS is a prettydef macro for saving and loading the * 

value of ^horrible 1 variables. A prettydef * 

command of the form (HORRIBLEVARS varj ... var n ) + 

will cause appropriate expressions to be written * 

which will restore the values of var^ ... var R * 

when the file is loaded. The values of var i ... ♦ 

var n are all printed by the same operation, so ♦ 

that they may contain cross references to common ♦ 

structures. * 



by resetting the file pointer using sfptr . + 

Note: hprint is intended primarily for output to disk files, since tho ♦ 

algorithm depends on being able to reset the file pointer. If file is not * 

a disk file, a temporary file is opened, x is printed on it, and then that + 

file is copied to the final output file. ~ ♦ 
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+ 21 .8 Typescript Files 



+ A typescript file is a 'transcript 1 of all of the input and output on a 

+ terminal. The following function enables transcript files for INTERLISP. 

+ dribble[ f ilenamejappendf lg] 42 Opens filename and begins recording the 

♦ typescript. If appendflg gT, the typescript will 
+ be appended to the end of filename . drtbble[ 3 

■ ■ 43 

+ closes the typescript file. 

+ dribble operates by redefining all of the various input and output functions, 

+ and then relinking the world. (Thus the first time it is called, there will bo 

+ a noticable delay before it returns.) The typescript produced is somewhat 

+ neater than that generated by TELNET because it does not show characters that 

♦ were erased via control-A or control-Q, i.e. the only input shown is that 
+ actually returned by the various input functions. 



+ dribble was written by D. C. Lewis. 

4 J? 

+ dribble also takes an extra argument, thawedf Ig . If thawedf Ig sT, the file 

+ will be opened in "thawed" mode. 

+ Only one typescript file can be active at any one point; i.e. 

«• dribble[f ilel] followed by dribble[ f ileS] will cause file! to be closed. 
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SECTION 22 
THE PROGRAMMER'S ASSISTANT AND LISPX 



22.1 Introduction 

This chapter describes one of the newer additions to INTERLISP: tho 
programmer's assistant. The central idea of the programmer's assistant is that 
the user, rather than talking to a passive system which merely responds to each 
input and waits for the next, is instead addressing an active intermediary, 
namely his assistant. Normally, the assistant is invisible to the user, and 
simply carries out the user's requests. However, since the assistant remembers 
what the user has told him, the user can instruct him to repeat a particular 
operation or sequence of operations, with possible modifications, or to undo 
the effect of certain specified operations. Like DWIM, the programmer's 
assistant is not implemented as a single function or group of functions, but is 
instead dispersed throughout much of INTERLISP. Like DWIM, the programmer's 
assistant embodies a philosophy and approach to system design whose ultimate 
goal is to construct a programming environment which would "cooperate" with the 
user in the development of his programs, and free him to concentrate more fully 
on the conceptual difficulties and creative aspects of the problem he is trying 
to solve. 



The programmer's assistant was designed and implemented by W. Teitelman. 
It is discussed in [Tei4]. 

Some of the features of the programmer's assistant have been described 
elsewhere, e.g. the UNDO command in the editor, the file package, etc. 
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Example 



The following dialogue, taken from an actual session at the console, gives the 
flavor of the programmer's assistant facility in INTERLISP. The user is about 
to edit a function loadf , which contains several constructs of the form 
(PUTD FN2 (GETD FN1 ) ) . The user plans to replace each of these by equivalent 
MOVD expressions. 



*-EDITF( LOADFF] [1] 

= LOADF 

EDIT 

*PP 

[LAMBDA (X Y) 
[ COND 

((NULL (GETD (QUOTE READSAVE ) ) ) 
(PUTD (QUOTE READSAVE) 

(GETD (QUOTE READ] 
(PUTD (QUOTE READ) 

(GETD (QUOTE REED))) 
(NLSETQ (SETQ X (LOAD X Y) ) ) 
(G>UTD (QUOTE READ) 

(GETD (QUOTE READSAVE))) 

X] 

«F PUTD (1 MOVD) [2] 
*3 (XTRR 2) [3] 

= XTR 

*0P [4] 
= 0 P 

(HOVD (QUOTE READSAVE) (QUOTE READ) ) 

*(SW 2 3) C.5] 



At [1], the user begins to edit loadf . At [2] the user finds PUTD and replaces 
it by MOVD . He then shifts context to the third subexpression, [3], extracts 
its second subexpression, and ascends one level [4] to print and result. The 
user now switches the second and third subexpression [5], thereby completing 



We prefer to consider the programmer's assistant as the moving force behind 
this type of spelling correction (even though the program that does the 
work is part of the DWIM package) . Whereas correcting SPRINT to PRINT , or 
XTRR to XTR does not require any information about what this user is doing, 
correcting LOADFF to L0A0F clearly required noticing when this user dof inod 
loadf. 
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the operation for this PUTD. Note that up to this point, the user has not 
directly addressed the assistant. The user now requests that the assistant 
print out the operations that the user has performed, [6], and the user thon 
instructs the assistant to REDO FROM F, [7], meaning repeat the entire sequence 
of operations 15 through 20. The user then prints the current expression, and 
observes that the second PUTD has now been successfully transformed. 

*?? FROM F [6] 

15. *F PUTD 

16. Ml MOVD) 

17. *3 

18. *(XTR 2) 

19. *0 

20. «(SW 2 3) 

*REDO FROM F [7] 
ftp 

(MOVD (QUOTE REED) (QUOTE READ) ) 

The user now asks the assistant to replay the last three steps to him, [8]. 
Note that the entire REDO FROM F operation is now grouped together as a single 
unit, [9], since it corresponded to a single user request. Therefore, the usor 
can instruct the assistant to carry out the same operation again by simply 
saying REDO. This time a problem is encountered [10], so the user asks the 
assistant what it was trying to do [11]. 

*?? FROM -3 [8] 

19. *0 

20. *(SW 2 3) 

21. REDO FROM F [9] 
•F PUTD 

*(1 MOVD) 

« 3 

"(XTR 2) 
"0 

*(SW 2 3) 

"REDO 

PUTD ? [10] 

*?? -1 [11] 

22. REDO 
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*F PUTD 
*(1 HOVD) 
*3 

*(XTR 2) 
*0 



The user then realizes the problem is that the third PUTO is misspelled in the 
definition of LOADF (see page 22.2). He therefore instructs the assistant to 
USE @UT0 FOR PUTD, [12], and the operation now concludes successfully. 



*USE (2UTD FOR PUTO [12] 
*P 

(MOVD (QUOTE READSAVE) (QUOTE READ)) 
a? pp 

[LAMBDA (X Y) 
[COND 

((NULL (GETD (QUOTE READSAVE) ) ) 
(MOVD (QUOTE READ) 

(QUOTE READSAVE] 
(MOVD (QUOTE REED) 

(QUOTE READ) ) 
(NLSETQ (SETQ X (LOAD X Y))) 
(MOVD (QUOTE READSAVE) 
(QUOTE READ)) 

X] 

*OK 
LOADF 



An important point to note here is that while the user could have defined a 
macro to execute this operation, the operation is sufficiently complicated that 
he would want to try out the individual steps before attempting to combine 
them. At this pointy he would already have executed the operation once. Then 
he would have to type in the steps again to define them as a macro , at which 
point the operation would only be repeated once more before failing. Then the 
user would have to repair the macro, or else change @UTD to PUTD by hand so 
that his macro would work correctly. It is far more natural to decide after 
trying a series of operations whether or not one wants them repeated or 
forgotten. In addition, frequently the user will think that the operation(s) 
in question will never need be repeated, and only discover afterwards that he 
is mistaken, as occurs when the operation was incorrect, but salvageable: 
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sup 

(LAMBDA (STR FLGCQ VRB) ""COMMENT** ( PROG 4 & LP1 & LP2 & &)) 

*-5 -1 P 

(RETURN (COND &)) 

M-2 ((EO BB (QUOTE OUT) ) BB] [1] 

ft p 

(RETURN (& BB) (COND &)) [2] 

•UNDO 

(-2 --) UNDONE 

*2 P 

(COND (EXPANS & & T)) 
*REDO EO 
p 

(COND (& BB) (EXPANS & & T) 



Here the operation was correct, [1], but the context in which it was executed, 
[2], was wrong. 

This example also illustrates one of the most useful functions of the 
programmer's assistant: its UNDO capability. In most systems, if a user 
suspected that a disaster might result from a particular operation, e.g. an 
untested program running wild and chewing up a complex data structure, he would 
prepare for this contingency by saving the state of part or all of his 
environment before attempting the operation. If anything went wrong, he would 
then back up and start over. However , saving/dumping operations are usually 
expensive and time consuming, especially compared to a short computation, and 
are therefore not performed that frequently, 'and of course there is always the 
case when diaster strikes as a result of a 'debugged 1 or at least innocuous 
operation, as shown in the following example: 



-(MAPC ELTS (FUNCTION (LAMBDA (X) (REMPROP X (QUOTE MORPH] [1] 

NIL 

-UNDO [2] 
MAPC UNDONE. 

-USE ELEMENTS FOR ELTS [3] 
NIL 



The user types an expression which removes the property MORPH from every member 
of the list ELTS [1], and then realizes that he meant to remove that property 
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only from those members of the list ELEMENTS, a much shorter list. In other 
words, he has deleted a lot of information that he actually wants saved. Ho 
therefore simply reverses the effect of the MAPC by typing UNDO [2], and then 
does what he intended via the USE command [3]. 

22.2 Overview 

The programmer's assistant facility is built around a memory structure callocl 
the 'history list. 1 The history list is a list of the information associated 
with each of the individual 'events' that have occurred in the system, where 
each event corresponds to one user input. 4 For example, (XTR 2) ([3] on page 
22.2) is a single event, while REDO FROM F ([7] on page 22.3) is also a singlo 
event, although the latter includes executing the operation (XTR 2), as well as 
several others . 

Associated with each event on the history list is its input and its value, plus 
other optional information such as side-effects, formatting information , otc. 
If the event corresponds to a history command, e.g. REDO FROM F, the input 
corresponds to what the user would have had to type to execute the samo 
operation( s ) , although the user's actual input, i.e. the history command, is 
saved in order to clarify the printout of that event ([9] on page 22.3). Mote 
that if a history command event combines several events, it will have more than 
one value : 



For various reasons, there are two history lists: one for the editor, and 
one for lispx , which processes inputs to evalqt and break , see page 22.44. 
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-(LOG (ANT I LOG 4)) 
4.0 

-USE 4.0 40 400 FOR 4 

4.0 

40 .0 

ARG NOT IN RANGE 
400 



-USE -40.0 -4.00007 -19. 

-40 .0 

-4.00007 

-19.0 

-USE LOG ANT I LOG FOR ANT I LOG LOG IN -2 AND -1 

4.0 

40.0 

400.0 

4 .00007 

19.0 

-?? 



4. USE LOG ANTILOG FOR ANT I LOG LOG IN -2 -1 
-( ANTILOG (LOG 4.0)) 
4.0 

-(ANTILOG (LOG 40)) 
40.0 

-(ANTILOG (LOG 400)) 
400.0 

-(ANTILOG (LOG -40.0)) 
40.0 

-(ANTILOG (LOG -4.00007)) 
4 .00007 

-(ANTILOG (LOG -19.0)) 
19.0 

3. USE -40.0 -4.00007 -19.0 
-(LOG (ANTILOG -40.0)) 
-40.0 

-(LOG (ANTILOG -4.00007)) 
-4.00007 

-(LOG (ANTILOG -19.0)) 
-19.0 

2. USE 4.0 40 400 FOR 4 
-(LOG (ANTILOG 4.0)) 
4.0 

(LOG (ANTILOG 40.0) 
40.0 

-(LOG (ANTILOG 400)) 

1. -(LOG (ANTILOG 4)) 
4.0 



As new events occur, existing events are aged, and the oldest event is 
'forgotten.' For efficiency, the storage used to represent the forgotten event 
is cannibalized and reused in the representation of the new event, so tho 
history list is actually a ring buffer. The size of this ring buffer is a 



22.7 



system parameter called the 'time-slice . ' Larger time-slices enable longer 
'memory spans, 1 but tie up correspondingly greater amounts of storage. Since 
the user seldom needs really 'ancient history,' and a NAME and RETRIEVE 
facility is provided for saving and remembering selected events, a relatively 
small time slice such as 30 events is more than adequate, although some users 
prefer to set the time slice as large as 100 events. 

Events on the history list can be referenced in a number of ways. The output 
on page 22.9 shows a printout of a history list with time-slice 10. The 
numbers printed at the left of the page are the event numbers. More recent 
events have higher numbers; the moist recent event is event number 52, the 
oldest and about- to-be- forgotten event is number 37,^ At this point in time, 
the user can reference event number 51, RECOMPILE'! EDIT)., by its event number, 
51; its relative position, -2 (because it occurred two events back from tho 
current time), or by a 'description' of its input, e.g. (RECOMPILE (EDIT)), or 
(& (EDIT)), or even just EDIT. As new events occur, existing events retain 
their absolute event numbers, although their relative positions change. 

Similarly, descriptor references may require mdre precision to refer to an 
older event. For example, the description RECOMPILE would have sufficed to 
refer to event 51 had event 52, also containing a RECOMPILE, not intervened. 
Event specification will be described in detail later. 



Initially 30 events. The time-slide can be changed with the function 
changeslice , page 22.54, 



When the event number of the current event is 100, the next event will bo 
given number 1. (If the time slice is greater than 100, the 'roll-over 1 
occurs at the next highest hundred, so that at no time will two events ever 
have the same event number. For example, if the time slice is 150, event 
number 1 follows event number 200.) 
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to?? 



52. ... HIST UNDO 

-RECOMPILE(HIST) 
HIST.COM 

•-RECOMPILE (UNDO) 

UN0O.COM 
51 . -RECOMPILE(EDIT) 

EDIT.COM 
50. -LOGOUT] 

49. -MAKEFILES] 

(EDIT UNDO HIST) 
48. -EDITF(UNDOLISPX) 

UNDOLISPX 
47. REDO GETD 

-GETD(FIE) 

(LAMBDA (X) (MAPC X (F/L (PRINT X)))) 

46. -UNDO 
FIE 

45. -GETD(FIE) 

(LAMBDA (X) (MAPC X (FUNCTION (LAMBDA (X) (PRINT X))))) 

44. -FIE] 
NIL 

43. -DEF I NEQ( (FIE (LAMBDA (X) (MAPC X (F/L (PRINT X)))))) 

(FIE) 
42. REDO GETD 

-GETD(FIE) " 

(LAMBOA (Y) Y) 
41. -UNDO 

MOVD 
40. REDO GETD 

-GETD(FIE) 

(LAMBDA (X) X) 
39. -MOVD(FOO FIE) 

FIE 

38. -DEFINEQ((FOO (LAMBDA (X) X))) 

(FOO) 
37. -GETO(FIE) 

(LAMBDA (Y) Y) 



The most common interaction with the programmer's assistant occurs at. the top 
level evalgt , or in a break, where the user types in expressions for 
evaluation, and sees the values printed out. In this mode, the assistant acts 
much like a standard LISP evalgt , except that before attempting to evaluate an 
input, the assistant first stores it in a new entry on the history list. Thus 
if the operation is aborted or causes an error, the input is still saved and 
available for modification and/or reexecution. The assistant also notes new 
functions and variables to be added to its spelling lists to enable future 
corrections. Then the assistant executes the computation (i.e. evaluates the 
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form or applies the function to its arguments), saves the value in the entry on 

the history list corresponding to the input, and prints the result, followed by 

7 

a prompt character to indicate it is again ready for input.' 

If the input typed by the user is recogni2ed as a history command, the 
assistant takes special action. Commands such as UNDO, ??, -NAME-, . and RETRIEVE 
are immediately performed. Commands that involved reexecution of previous 
inputs, e.g. REDO and USE, are achieved by computing the corresponding input 
expression( s) and then unreading them. The effect of this unreading operation 
is to cause the assistant's input routine, lispxread , to act exactly as though 
these expression were typed in by the user. Except for the fact that these 
inputs are not saved on new and separate entries on the history list, but 
associated with the history command that generated them, they are processed 
exactly as though they had been typed. 

The advantage of this implementation is that it makes the programmer's 
assistant a callable facility for other system packages as well as for users 
with their own private executives. For example, break 1 accept user inputs, 
recognizes and executes certain break commands and macros, and interprets 
anything else as INTERLISP expressions for evaluation. To interface break! 
with the programmer's assistant required three small modifications to brcakl ; 
(1) input was to be obtained via lispxread instead of read ; (2) instead of 
calling eval or apply directly, break! was to give those inputs it could not 



The function that accepts a user input, saves the input on the history 
list, performs the indicated computation or history command, and prints the 
result, is lispx. lispx is called by evalqt and break 1 , and in most cases, 
is synonymous with 'programmer's assistant .' However, for various reasons, 
the editor saves its own inputs on a history list, carries out the 
requests, i.e. edit commands, and even handles undoing independently of 
lispx. The editor only calls lispx to execute a history command, such as 
REDO, USE, etc. Therefore we use the term assistant (loosely) when the 
discussion applies to features shared by evalqt , break and the editor, and 
the term lispx when we are discussing the specific function. 
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interpret to lispx , and (3) any commands or macros handled by break 1 , i.e. not 
given to lispx , were to be stored on the history list by break! by calling tho 
function historysave , a part of the assistant package. 

Thus when the user typed in a break command, the command would be stored on tho 
history list as a result of (3), If the user typed in an expression for 
evaluation, it would be evaluated as before, with the expression and its valuo 
both saved on the history list as a result of (2). Wow if the user entered a 
break and typed three inputs: EVAL, (CAR !VALUE), and OK, at the next break, ho 
could achieve the same effect by typing REDO FROM EVAL. This would cause tho 
assistant to unread the three expressions EVAL, (CAR !VALUE)„ and OK. Becauso 
of (1), the next 'input 1 seen by breakl would then be EVAL, which break 1 would 
interpret. Next would come (CAR ! VALUE), which would be given to lispx to 
evaluate, and then would come OK, which breakl would again process. Thus, by 
virtue of unreading, history operations will work even for those inputs not 
interpretable by lispx , in this case, EVAL and OK, 

The net effect of this implementation of the programmer's assistant is to 
provide a facility which is easily inserted at many levels, and embodies a 
consistent set of commands and conventions for talking about past events. This 
gives the user the subjective feeling that a single agent is watching 
everything he does and says, and is always available to help. 

22.3 Event Specification 

All history commands use the same conventions and syntax for indicating which 
event or events on the history list the command refers to, even though 
different commands may be concerned with different aspects of the corresponding 
event(s) , .-e.g. side-effects, value, input, etc. Therefore, before discussing 
the various history commands in the next section, this section describes the 
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types of event specifications currently implemented. All examples refer to the 
history list on page 22.9. 



An event address identifies one event on the history list. it consists of a 
sequence of •commands 1 for moving an imaginary cursor up or down the history 
list, much in the manner of the arguments to the @ command in break (see 
Section 15). The event identified is the one 'under' the imaginary cursor when 
there are no more commands. (IT any command fails, an error is generated and 
the history command is aborted.) 

The commands are interpreted as follows: 



n (n > 1) 

n (n < -1) 
•-atom 



move forward n events, i.e. in direction of 
increasing event number. If given as the first 
•command,' n specifies the event with event number 
n . 

move backward -n events. 

specifies an event whose Junction matches atom 
(i.e. for apply format only), e.g. whereas FIE 
would refer to event ^7, «-FIE would refer to event 



44. Similarly, EDS 
whereas *-EDS event 48 



would specify event 51, 



next search is to go forward instead of backward, 
(if given as the first •command' , next search 
begins with last, i.e. oldest, event on history 
list), e.g. LAMBDA refers to event 38; 

MAKEFILES - RECOMPILE refers to event 51. 

next object is to be searched for, regardless of 
what it is, e.g. F -2 looks for an event 
containing a -2. 

next object (presumably a pattern) is to be 
matched against values, instead of inputs, e.g. = 
UNDO refers to event 49; 45 = FIE refers to event 
43; *» a LAMBDA refers to event 37. 

specifies the event last located. 



+ 5UCHTHAT pred 



specifies an event for which pred , a function of 



8 



i.e. EDalt-mode, 
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two arguments, when given the input portion of the 
event as its first argument, and the event itself 
as its second argument, returns true. E.g., 
SUCHTHAT (LAMBDA (X Y) (MEMB (QUOTE *ERROR* ) Y ) ) 
specifies an event in which an error occurred.^ 



pat anything else specifies an event whose input 

contains an expression that matches pat as 
described in section 9. 



Mote: each search skips the current event, i.e. each command always moves the 
cursor. For example, if F00 refers to event n D F00 FIE will refer to some 
event before event n, even if there is a FIE in event n . 

An event specif ication specifies one or more events: 

FROM #1 THRU #2 
#1 THRU #2 



the sequence of events from the 
event with address #1 through event with address 
*Z, 10 e.g. FROM GETD THRU 49 specifies events 47, 
48, and 49. #1 can be more recent than #2, e.g. 
FROM 49 THRU GETP specifies events 49, 48, and 47 
(note reversal of order). 



FROM #1 TO #2 
#1 TO #2 



Same as THRU but does not include event #2 



FROM #1 



Same as FROM #1 THRU -1, e.g. FROM 49 specifies 
events 49, 50, 51, and 52. 



THRU #2 



Same as FROM -1 THRU #2, e.g. THRU 49 specifies 
events 52, 51, 50, and 49. Note reversal of 
order. 



TO 



Same as FROM -1 TO #2, 



#1 AND *2 AND ... AND #n i.e. a sequence of event specifications separated 



See page 22.44 for discussion of the format of events on the history list. 



10 



i.e. the symbol #1 corresponds to all words between FROM and THRU in tho 
event specification, and #2 to all words from THRU to the end of the event 
specification. For example, in FROM FOO 2 THRU FIE -1, #1 is (FOO 2), and 
#2 is (FIE -1). 
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by AMD's, e.g. FROM 4 7 TO LOGOUT would bo 
equivalent to 47 AND 48 AND MAKEFILES. 



ALL #1 specifies all events satisfying #1, e.g. ALL LOAD, 

ALL SUCHTHAT FOO. 

empty i.e. nothing specified, same as -1, unless last 

event was an UNDO, in which case same as -2. 

@ atom refers to the events named by atom, via the NAME 

command, page 22.26 e.g., if the user names a 
particular event or events FOO, © FOO specifies 
those events. 

@@ £ i is an event specification and interpreted as 

above, but with respect to the archived history 
list, as specified on page 22.27. 



If no events can be found that satisfy the event specification, spelling 
correction on each word in the event specification is performed using 
lispxf indsplst as a spelling list, e.g. REDO 3 THRUU 6 will work correctly. If 
the event specification still fails to specify any events after spoiling 
correction, an error is generated. 

22.4 History Commands 

All history commands can he input as either lists, or as lines (see read I i ne 
Section 14 , and also page 22.47). 

£ is used to denote an event specification . Unless specified otherwise. £ 
omitted is the same as £ , e.g. REDO and REDO ^1 are the same. 



REDO £ redoes the event or events specified by d, e.g. 

REDO FROM -3 redoes the last three events. 

REDO £ N TIMES redoes the event or events specified by £ N timos, 

e.g. REDO 10 TIMES redoes the last event ten 
times. If n is not a positive number, e.g. REDO 
MANY TIMES,"" the effect is the same as though n 
were infinite: the events(s) are repeated until 
an error occurs, or user types control-d. 



For example, if the user types (NCONC FOO FIE), he can then type UNDO, 
followed by USE NCONC 1. 
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USE vars FOR args IN i substitutes vars for args in d, and redoes the 

result, e.g. 

USE LOG ANTILOG FOR ANTILOG LOG IN -2 AND -1. 
Substitution is done by esubst , Section 9, and is 
carried out as described below. 

USE vars t FOR args. AND ... AND vars FOR args IN i 

More general form of USE command. See description 
of substitution algorithm below. 

Every USE command Involves three pieces of information: the variables to be 
substituted, the arguments to be substituted for, and an event specif ication , 

f r> 

which defines the expression (input) in which the substitution takes place. 

If args are omitted, i.e. the form of the command is USE vars IN l 9 or just USE 
vars (which is equivalent to USE vars IN -1), and the event referred to was 
itself a USE command p the arguments and expression substituted into are tho 
sane as for the indicated USE command. In effect, this USE command is thus a 
continuation of the previous USE command. For example, on page 22.7, when the 
user types (LOG (ANTILOG 4)), followed by USE 4.0 40 400 FOR 4, followed by 
USE -40.0 -4.00007 -19., the latter command is equivalent to 
USE -40.0 -4.00007 -19. FOR 4 IN -2. 

*f args are omitted and the event referred to was not a USE command, 
substitution is for the operator in that command, i.e. if a lispx input, the 
name of the function, if an edit command, the name of the command. For example 
ARGLIST(FF) followed by USE CALLS is equivalent to USE CALLS FOR ARGLIST. 

If £ is omitted, but args are specified, the first member of args is used for 



The USE command is parsed by a small finite state parser to distinguish tho 
variables and arguments. For example, USE FOR FOR AND AND AND FOR FOR will 
be parsed correctly. 
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t, e.g. USE PUTD FOR @UTD is equivalent to USE PUTD FOR @UTD IN F @UTD> 



If the USE command has the same number of expressions as arguments, the 
substitution procedure is straightforward,/^ i.e. USE X Y FOR U V moans 
substitute X for U and Y for V, and is equivalent to USE X FOR U AND Y FOR V. 
However, the USE command also permits distributive substitutions, i.e. 
substituting several expressions for the same argument. For example, 
USE A B C FOR X means first substitute A for X then substitute B for X (in a 
new copy of the expression), then substitute C for X. The effect is the same 
as three separate USE commands. Similarly, USE A B C FOR D AND X Y Z FOR W is 
equivalent to USE A FOR D AND X FOR W, followed by USE B FOR D AND Y FOR W, 
followed by USE C FOR D AND Z FOR W. USE A B C FOR D AND X FOR Y 15 also 
corresponds to three substitions, the first with A for D and X for Y, the 
second with B for D, and X for Y, and the third with C for D, and again X for 
Y. However, USE A B C FOR D AND X Y FOR Z is ambiguous and will cause an 
error. Essentially, the USE command operates by proceeding from left to right 
handling each •AND' separately. Whenever the number of expressions exceeds the 
number of expressions available, the expressions multiply. ^ 
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14 



15 



16 



The F is inserted to handle correctly the case where the first member of 
args is a number, e.g. USE 4.0 4.0 400 FOR 4. Obviously the user means find 
the event containing a 4 and perform the indicated substitutions, whereas 
USE 4.0 40 400 FOR 4 IN 4 would mean perform the substitutions in event 
number 4 . 

Except when one of the arguments and one of the variables are the same, 
e.g. USE X Y FOR Y X, or USE X FOR Y AND Y FOR X. This situation is noticed 
v/hen parsing the command, and~handled correctlyT 

or USE X FOR Y AND A B C FOR D. 

Thus USE A BCD FOR E F means substitute A for E at the same time as 
substituting B for F, then in another copy of the indicated expression, 
substitute C for E and D for F. Note that this is also equivalent to 
USE A C FOR E AND B D FOR F. 
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FIX £ puts the user in the editor looking at a copy of 

the input(s) for t % Whenever the user exits via, 
OK, the result is unread and reexecuted exactly as 
with REDO. 



FIX is provided for those cases when the modifications to the input(s) are not 
of the type that can be specified by USE, i.e. not substitutions. For example: 



-(DEFINEQ F00 ( LAMBDA (X) (FIXSPELL SPELLINGS2 X 70] 

INCORRECT DEFINING FORM 
FOO 

-FIX 

EDIT 
*p 

(DEFINEQ FOO { LAMBDA & &)) 

*(LI 2) 
OK 

(FOO) 



The user can also specify the edit command(s) to lispx , by typing - followed by 
the command(s) after the event specification, e.g. FIX - (LI 2). In this case, 
the editor will not type EDIT, or wait for an OK after executing the commands. 



Implementation of REDO, USE, and FIX 



The input portion of an event is represented internally on the history list 

simply as a linear sequence of the expressions which were read. For example, 

an input in apply format is a list consisting of two expressions, and an input 

17 

in eval format is a list of just one expression. Thus if the user wishes to 

convert an input in apply format to eval format, he simply moves the function 
name inside of the argument list: 



For inputs in eval format, i.e. single expressions, FIX calls the editor so 
that the current expression is that input, rather than the list consisting 
of that input - see the example on the preceding page. However, the entire 
list is actually being edited. Thus if the user typed t p in that example, 
he would see ( (DEFINEQ FOO &)). 
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«-MAPC( FOOFNS (F/L (AND (EXPRP X) (PRINT X] 
NIL 

-EXPRP(FOOl) 
T 

-FIX MAPC 

EDIT 

*P 

(MAPC (FOOFNS &)) 

*(BO 2) 

*(LI 1) 
*p 

((MAPC FOOFNS &)) 
OK 

FOOl 
FIE2 
FUM 
NIL 



By simply converting the input from two expressions to one expression, the 
desired effect, that of mapping down the list that was the value of foofns , was 
achieved. 

REDO, USE, and FIX all operate by obtaining the input portion of the 
corresponding event, processing the input (except for REDO), and then storing 
it on the history list as the input portion of a new event. The history 
command completes operating by simply unreading the input. When the input is 
subsequently 'reread 1 , the event which already contains the input will be 
retrieved and used for recording the value of the operation, saving side- 
effects, etc.* instead of creating a new event. Otherwise the input is treated 
exactly the same as if it had been typed in directly. 

If i specifies more than one event, the inputs for the corresponding events are 
simply concatenated into a linear sequence, with special markers (called 
pseudo-carriage returns) representing carriage returns 40 inserted between each 



The value of the variable histsrO is used to represent a carriage return. 
For readability, this value is the string "<c.r. >" . Note that since the 
comparison is made using eg, this marker will never be confused with a 
string that was typed in by the user. 



22.18 



input to indicate where new lines start. The result of this concatenation is 
then treated as the input referred to by t. For example, when the user typed 
REDO FROM F ([7] on page 22.3) the inputs for the corresponding six events wore 
concatenated to produce: 

(F PUTD "<c.r.>"(l MOVD) M <c.r .>" 3 M <c .r . >"( XTR 2)"<c.r.>" 0 »<c .r . > M (SW 2 3)). 
Similarly, if the user had typed USE @UTD FOR PUTD IN 15 THRU 20, the above 
list would have been constructed, and then @UTD substituted for PUTD 
throughout it. 

The same convention is used for representing multiple inputs when a USE command 
involves sequential substitutions. For example, if the user types GETD(FOO) 
and then USE FIE FUM FOR FOO, the input sequence that will be constructed is 
(GETD (FIE) "<c.r GETD (FUH) ) , which is the result of substituting FIE for 
FOO in (GETD ( FOO) ) concatenated with the result of substituting FUH for FOO in 
(GETD (FOO)). 

Once such a multiple input is constructed, it is treated exactly the same as a 
single input, i.e. the input sequence is recorded in a new event, and then 
unread, exactly as described above. When the inputs are 1 reread, 1 the 'psoudo-- 
carriage-returns 8 are treated by lispxread and readline exactly as real 
carriage returns, i.e. they serve to distinguish between apply and eval formats 
on inputs to lispx , and to delimit line commands to the editor. Mote that once 
this multiple input has been entered as the input portion of a new event, that 
event can be treated exactly the same as one resulting from type in. In other 
words, no special checks have to be made when referencing an event, to see if 
it is simple or multiple. Thus, when the user types REDO following 
REDO FROM F, ([10] page 22.3) REDO does not even notice that the input 
retrieved from the previous event is (F PUTD "<c.r.>" ... (SW 2 3)) i.e. a 
multiple input, it simply records this input and unreads it. Similarly, when 
the user then types USE @UTD FOR PUTD on this multiple input, the USE command 
simply carries out the substitution, and the result is the same as though the 
user had typed USE @UTD FOR PUTD IN 15 THRU 20. 
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In sum, this implementation permits i to refer to a single simple event, or to 
several events, or to a single event originally constructed from several events 
(which may themselves have been multiple input events, etc.) without having to 
treat each case separately. 

History Commands Applied to History Commands 

Since history commands themselves do not appear in the input portion of events 
(although they are stored elsewhere in the event), they do not interfere with 
or affect the searching operations of event specifications. In effect, history 
commands are invisible to event specif ications . *® As a result, history commands 
themselves cannot be recovered for execution in the normal way. For example, 
if the user types USE A B C FOR 0 and follows this with USE E FOR D, he will 
not produce the effect of USE ABC FOR E (but instead will simply cause E to 
be substituted for D in the last event containing a D). To produce this 
effect, i.e. USE A B C FOR E, the user should type USE D FOR E IN USE. Tho 
appearance of the word REDO, USE or FIX in an event address specifies a search 
for the corresponding history command. (For example, the user can also type 
UNDO REDO.) It also specifies that the text of the history command itself bo 
treated as though it were the input. However, the user must remember that the 
context in which a history command is reexecuted is that of the current 
history, not the original context. For example, if the user types 
USE FOO FOR FIE IN -1, and then later types REDO USE, the -1 will refer to the 
event before the REDO, not before the USE. Similarly, if the user types 
REDO REDO followed by REDO REDO, he would cause an infinite loop, except for 
the fact that a special check detects this type of situation. 



With the exception described below under "History Commands that Fail". 
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History Commands that Fall 

The one exception to the statement that 'history commands are invisible to 
event specifications' occurs when a history command fails to produce any input. 
For example, suppose the user types USE LOG FOR ANTILOG AND ANTILOG FOR LOGG, 
causing lispx to respond LOGG ?. Since the USE command did not produce any 
input, the user can repair it by typing USE LOG FOR LOGG (i.e. does not have to 
specify IN USE). This latter USE command will invoke a search for LOGG, which 
mill find the bad USE command, lispx then performs the indicated substitution, 
and unreads USE LOG FOR ANTILOG AND ANTILOG FOR LOG. In turn, this USE command 
invokes a search for ANTILOG, which, because it was not typed in but reread. 
ignores the bad USE command which was found by the earlier search for LOGG, and 
which is still on the history list. In other words, htstori/ commands that Jail 
to produce input are visible to searches arising from event specifications 
typed in by the user, but not to secondary event specifications . 

In addition, if the most recent event is a history command which failed to 
produce input, a secondary event specification will effectively back up the 
history list one event so that relative event numbers for that event 
specification will not count the bad history command. For example, suppose the 
user types USE LOG FOR ANTILOG AND ANTILOG FOR LOGG IN -2 AND -1, and after 
lispx types LOGG 7, the user types USE LOG FOR LOGG. He thus causes the command 
USE LOG FOR ANTILOG AND ANTILOG FOR LOG IN -2 AND -1 to be constructed and 
unread. In the normal case, -1 would refer to the last event, i.e. the 'bad' 
USE command, and -2 to the event before it. However, in this case, -1 refers 
to the event before the bad USE command, and the -2 to the event before that. 
In short, the caveat that "the user must remember that the context in which a 
history command is reexecuted is that of the current history, not the original 
context" does not apply if the correction is performed immediately. 
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More History Commands 



RETRY i similar to REDO except sets helpclock so that any 

errors that occur while executing t will causo 
breaks. 

... vars similar to USE except substitutes for the (first) 

operand. 

For example, EXPRP(FOO) followed by ... FIE FUM is equivalent to 
USE FIE FUM FOR TOO. See also event 52 on page 22.9. 



?? t prints history list. If t is omitted, ?? prints 

the entire history list, beginning with most 

recent events. Otherwise ?? prints only those 

events specified in i (and in the order 

specified), e.g. ?? -1, ?? 10 THRU 15. etc. 

?? commands are not entered on the history list, and so do not affect relative 
event numbers. In other words, an event specification of -1 typed following a 
?? command will refer to the event immediately preceding the ?? command. 

?? will print the history command, if any, associated with each event as shown 
at [9] on page 22.3 and page 22.7. Note that these history commands are not 
preceded by prompt characters, indicating they are not stored as input. 



?? prints multiple input events under one event number (see page 22.7), 

Since events are initially stored on the history list with their value field 
equal to bell (control-G), if an operation fails to complete for any reason, 
e.g. causes an error, is aborted, etc., its 'value 1 will be bell. This is the 
explanation for the blank line in event 2, page 22.7, and event 50, page 22.9. 
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REDO, RETRY, USE, . . . , and FIX commands, i.e. those commands that reoxecuto 
previous events, are not stored as inputs, because the input portion for 
these events are the expressions to be 'reread'. The history commands 
UNDO, NAME, RETRIEVE, BEFORE, and AFTER are recorded as inputs, and ?? 
prints them exactly as they were typed. 
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?? is implemented via the function printhistory , page 22.60, which can also bo 
called directly by the user. 



UNDO t 



UNDO i : x 



1 



undoes the side effects of the specified events. 
For each event undone, UNDO prints a message: e.g. 
RPLACA UNDONE , REDO UNDONE etc. If nothing is 
undone because nothing was saved, UNDO typos 
NOTHING SAVED. If nothing was undone because the 
event(s) were already undone, UNDO typos 
ALREADY UNDONE. If t is empty, UNDO searches back 
for the last event that contained 



was not 
command 
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U S3 



one, and itself was 



side 
not 



effects , 
an UNDO 



Each x. refers to a message printed by DWIM in the 
event(s) specified by d. The side effects of the 
corresponding DWIM corrections, and only those 
side effects, are undone. 



For example, if the message PRINTT [IN FOO] -> PRINT were printed, 



UNDO 



PRINTT or UNDO : PRINT would undo the correction • 
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Note that the user can undo UNDO commands themselves by specifying the 
corresponding event address, e.g. UNDO -3 or UNDO UNDO. 



UNDOing events in the reverse order from which they were executed is 
guaranteed to restore all pointers correctly, e.g. to undo all effects of 
last five events, perform UNDO THRU -5, not UNDO FROM -5. Undoing out of 
order may have unforseen effects if the operations are dependent . For 
example, if the user performed (NCONC1 FOO FIE), followed by 
(NCONC1 FOO FUH), and then undoes the (NCONC1 FOO FIE), he will also have 
undone the (NC0NC1 FOO FUM). If he then undoes the (NCONC1 FOO FUM), ho 
will cause the FIE to reappear, by virtue of restoring FOO to its stato 
before the execution of (NC0NC1 FOO FUM). For more details, see page 
22.42. 



Some portions of the messages printed by DWIM are strings, e.g. the message 
FOO UNSAVED is printed by printing FOO and then " UNSAVED". Therefore, if 
the user types UNDO : UNSAVED, the DWIM correction will not be found. He 
should instead type UNDO : FOO or UNDO : SUNSAVEDS ( alt-modeUNSAVEDal t- 
mode, see R command in editor, section 9). 
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S is a special form of the USE command for conveniently specifying character 
substitutions. In addition, it has a number of useful default options in 
connection with events that involve errors. 

S x FOR y equivalent to USE $xS FOR Sy$ 

For example, the user types M0VD(F00 FOOSAVE T), he can then type $ FIE FOR FOO 
to perform HQVD(FIE FXESAVE T) . Note that USE FIE FOR FOO would perform 
MOVDCFIE FOOSAVE T). 

An abbreviated form of $ is available: 

S y x same as S x FOR y, i.e. y's are changed to x's. 

can also be written as S y TO x, $ y s x, or 
S y -> x. 

S does event location the same as the USE command, i.e. if IN is not 
specified, it searches for jj. 

After S finds the event, it looks to see if an error was involved in that 
event, and if the indicated character substitution can be performed in the 
offender. If so, $ assumes the substitution refers to the offender, performs 
the substitution, and then substitutes the result for the offender throughout. 
For example, the user types (PRETTYDEF FOOFNS J-'FOO FOOVARS) causing a 
U.B.A. FOOOVARS error message. The user can now type S 00 0, which will change 
FOOOVARS to FOOVARS, but not change FOOFNS or FOO. 

However, unlike USE, S can only be used to specify one substitution at a 
time. 

V/henever an error occurs, the object of the error message, called the 
offender, is automatically saved on that event *s entry in the history list, 
under the property *ERROR*. 
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If an error did occur In the specified event, the user can also omit specifying 
X» in which case the offender is used. Thus, the user could have corrected the 
above example by simply typing S FOOVARS. Similarly, if the user types 
LOAD(PRSTRUC PROP), causing the error FILE NOT FOUND PRSTRUC, he can request 
the file to be loaded from LISP 1 s directory by simply typing $ <LXSP>$. Since 
esubst is used for substituting, this is equivalent to performing 
(R PRSTRUC <LISP>5) on the event, and therefore replaces PRSTRUC by 
<LISP>PRSTRUC (see Section 9). Note also the usefulness of $ meaning: put 
a • in front of the offender. 

S also works for events in the editor. For example, if the user typos 
(MOVE COND 33 2 TO BEFORE HERE), and editor types 33 ?, the user can type S 3, 
causing 3 to be substituted for 33 in the HOVE command. 

Finally, the user can omit both x and This specifies that two alt-modes bo 
packed onto the end of the offender, and the result substituted throughout the 
specified event. For example, suppose the user types to the editor 
(MOVE 3 2 TO AFTER CONDD 1), and gets the error message CONDD ?. because the 
find command failed to find CONDD. S will cause the edit command 
(MOVE 3 2 TO AFTER CONDDSS 1 ) to be executed, which will search for an atom 
that is "close" to CONDD in the sense used by the spelling corrector (see 
pattern type Ob, Section 9). 26 

Mote that S never searches for an error. Thus, if the user typos 
LOAD( PRSTRUC PROP) causing a FILE NOT FOUND error, types CLOSEALLO, and then 
types S <LISP>S, lispx will complain that there is no error in CLOSEALL(). In 



The same effect could be achieved by $ COND, which specifies substituting 
COND for CONDD, but not by S CONDDSS, since the latter is equivalent to 
performing (R CONDD CONDDSS) on the event, which would result in 
CONDDCONDDCONDD being substituted for CONDD (as described in Section 9). 
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this case, the user would have to type $ <LXSP>$ IN LOAD, or 
S PRS <LISP>PRS (which would cause a search for PRS) . 

Note also that S operates on input, not on programs. If the user types FOO(), 
and within the call to FOO gets a U.D.F. CONDD error, he cannot repair this by 
$ COND. lispx will type CONDD NOT FOUND IN FOO( ) . 

8 & ft . 

NAME atom t saves the event(s) (including side effects) 

specified by i on the property list of atom (under 
the property HISTORY) e.g. NAME FOO 10 THRU . 15. 
NAME commands are undoable. 

RETRIEVE atom Retrieves and reenters on the history list the 

events named by atom . Causes an error if atom was 
not named by a NAME command. 

For example, if the user performs NAME FOO 10 THRU 15, and at some time later 
types RETRIEVE FOO, 6 new events will be recorded on the history list (whether 
or not the corresponding events have been forgotten yet). Note that RETRIEVE 
does not reexecute the events, it simply retrieves them. The user can then 
REDO, UNDO, FIX, etc. any or all of these events. Note that the user can 
combine the effects of a RETRIEVE and a subsequent history command in a single 
operation by using an event specification of the form @ atom, as described on 
page 22.14, e.g. REDO @ FOO is equivalent to RETRIEVE FOO, followed by an 
appropriate REDO. 27 Note that UNDO & FOO and ?? 0 FOO are permitted. 

BEFORE atom undoes the effects of the events named by atom . 

AFTER atom undoes a BEFORE atom. 



Actually, REDO @ FOO is better than RETRIEVE followed by REDO since in the 
latter case, the corresponding events would be entered on the history list 
twice, once for the RETRIEVE and once for the REDO. 
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BEFORE/AFTER provide a convenient way of flipping back and forth between two 
states, namely that state before a specified event or events were executed, and 
that state after execution. For example, if the user has a complex data 
structure which he wants to be able to interrogate before and after certain 
modifications, he can execute the modifications, name the corresponding events 
with the NAME command, and then can turn these modifications off and on via 
BEFORE or AFTER commands. 2 ^ Both BEFORE and AFTER are NOPs if the atom was 
already in the corresponding state; both generate errors if atom was not namod 
by a NAME command. 

Mote: since UNDO,, NAME , RETRIEVE, BEFORE, and AFTER are recorded as inputs they 
can be referenced by REDO, USE, etc, in the normal way. However, the user 
must again remember that the context in which the command is reexecuted is 
different than the original context. For example, if the user typos 
NAME FOO DEFINEO THRU COMPILE, then types ... FIE, the input that will bo 
reread will be NAME FIE DEFINEO THRU COMPILE as was intended, but both DEFINEO 
and COMPILE, will refer '-to the most recent event containing those atoms, namely 
the event consisting of NAME FOO DEFINEO THRU COMPILES 

ARCHIVE t records the events specified by i on a permanent 

history list. This history list can be referenced 
by preceding a standard event specification with 
@@, e.g. ?? 8@ prints the archived history list, 
REDO @@ -1 will recover the corresponding event 
from the archived history list and redo it, etc. 

The user can also provide for automatic archiving of selected events by 
appropriately defining archivefn , as described on page 22.33. 



The alternative to BEFORE/AFTER for repeated switching back and forth 
involves UNDO, UNDO of the UNDO, UNDO of that etc. At each stage, the user 
would have to locate the correct event to undo, and furthermore would run 
the risk of that event being 'forgotten 1 if he did not switch at least once 
per time-slice. 
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FORGET t 



permanently erases the record of the side effects 
for the events specified by t . If t is omitted* 
forgets side effects for entire history list. 



FORGET is provided for users with space problems. For example, if the user has 
just performed set s, rplaca s, rplacd s, putd , remprop s, etc. to release 
storage, the old pointers would not be garbage collected until the 
corresponding events age sufficiently to drop off the end of the history list 
and be forgotten. FORGET can be used to force immediate forgetting (of the 
side-effects only). FORGET is not undoable (obviously). 

22.5 Miscellaneous Features and Commands 

TYPE-AHEAD is a command that allows the user to type-ahead an 

indefinite number of inputs. 

The assistant responds to TYPE-AHEAD with a prompt character of >. The user 
can now type in an indefinite number of lines of input, under errorsot 
protection. The input lines are saved and unread when the user exits the type- 
ahead loop with the command $G0 (alt-modeGO) . While in the type-ahead loop, ?? 
can be used to print the type-ahead, FIX to edit the type-ahead, and SO to 
erase the last input (may be used repeatedly). For example: 
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-TYPE-AHEAD 

.>SYSOUT(TEM) 

>MAKEFILE(EDIT) 

>BRECOMPILE( (EDIT WEDIT)) 

>F 

>S0 

\\F 

>SQ 

WBRECOMPILE 
>LOAD( WEDIT PROP) 
>BRECOMPILE( (EDIT WEDIT)) 

>F 

>MAKEFILE( BREAK ) 
>LISTFILES( EDIT BREAK) 
>SYSOUT(CURRENT) 
>LOGOUT] 
> ?? 

>SYSOUT(TEM) 
>MAKEFILE(EDIT) 
>LOAD( WEDIT PROP) 
>BRECOMPILE( (EDIT WEDIT) ) 

>F 

>MAKEFILE( BREAK) 
>LISTFILES( EDIT BREAK) 
>SYSOUT(CURRENT) 
>LOGOUT] 

>FIX 
EDIT 

*(R BRECOMPILE BCOMPL) 

((LOGOUT) (SYSOUT &) (LISTFILES &) 

(LOAD &) (MAKEFILE &) (SYSOUT &)) 

^(DELETE LOAD) 

*OK 

>SGO 



The TYPE-AHEAD command may be aborted 
current line of input. 
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(MAKEFILE &■) (F) (BCOHPL &) 



by SSTOP; control-E simply aborts the 



Mote that type-ahead can be addressed to the compiler » since it usos 
lispxread for input. Type-ahead can also be directed to the editor, but 
type-ahead to the editor and to lispx cannot be intermixed. 
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SBUFS (alt-modeBUFS) 



is a command for recovering the input buffers. 



Whenever an error occurs in executing a lispx input or edit command, or a 
control-E or control-D is typed, the input buffers are saved and cleared. The 
SBUFS command is used to restore the input buffers, i.e. its effect is exactly 
the same as though the user had retyped what was 'lost. 1 For example: 

*(-2 (SETQ X (COND ( (NULL Z) (CONS (user typed control-E) 

*P 

( COND (& &) (T &)) 
*2 

*SBUFS 

(-2 (SETQ X (COND ( (NULL Z) (CONS 
and user can now finish typing the (-2 ..) command. 

Note: the type-ahead does not have to have been seen by 1MTERLISP, i.e., 
echoed, since the system buffer is also saved. 

Input buffers are not saved on the history list, but on a free variable. Thus, 
only the contents of the input buffer as of the last clearbuf can ever bo 
recovered. However, input buffers cleared at evalqt are saved independently 
from those cleared by break or the editor. The procedure followed when the 
user types SBUFS is to recover first from the local buffer, otherwise from the 
top level buffer. 30 Thus the user can lose input in the editor, go back to 
evalqt , lose input there, then go back into the editor, recover the editor's 



The local buffer is stored on lispxbufs; the top level buffer on 
toplispxbufs . The forms of both buffers* are (CONS ( LINBUF ) (SYSBUF ) ) (see 
Section 14). Recovery of a buffer is destructive, i.e. SBUFS sets the 
corresponding variable to NIL. If the user types SBUFS when both lispxhuf s 
and toplispxbufs are NIL, the message NOTHING SAVED is typed, and an error 
generated; ~ ~ ,. 
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buffer, etc. Furthermore, a buffer cleared at the top can be recovered in a 
break, and vice versa. 

» ft a 

The following four commands, 00, !F, !E, and !N, are only recognized in the 
editor : 

DO com allows the user to supply the command name when it 

was omitted. (USE is used when a command name is 
incorrect ) . 

For example, suppose the user wants to perform 

(-2 (SETQ X (LIST Y Z))) but instead types just (SETQ X (LIST Y Z)). Tho 
editor will type SETQ ?, whereupon the user can type 00 -2. The effect is the 
same as though the user had typed FIX, followed by (LI 1), (-1 -2), and OK g 
i.e. the command (-2 (SETQ X (LIST Y Z))) is executed, DO also works if the 
last command is a line command. 

IF same as DO F. 

In the case of !F, the previous command is always treated as though it were a 
line command, e.g. if the user types (SETQ X &) and then !F, the effect is the 
same as though he had typed F (SETQ X &), not (F (SETQ X &)). 

IE same as DO E. Note IE works correctly for 

•commands' typed in eval or apply format. 

! N same as DO N. 
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control-U when typed in at any point during an input boing 

read by lispxread , permits the user to edit tho 
input before it is returned to the calling 
function. 

This feature is useful for correcting mistakes noticed in typing before the 
input is executed, instead of waiting till after execution and then performing 
an UNDO and a FIX. For example, if the user typos 
(DEFINEQ (F00 (LAMBDA (X) (FIXSPELL X and at that point notices the missing 
left parenthesis, instead of completing the input and allowing the error to 
occur, and then fixing the input, he can simply type control-U, 4 finish typing 
normally, whereupon the editor is called on (F00 (LAMBDA (X) (FIXSPELL X ], 
which the user can then repair, e.g. by typing (LI 1). If the user exits from 
the editor via OK, the (corrected) expression will be returned to whoever 

op 

called lispxread exactly as though it had been typed. If the user exits via 
STOP, the expression is returned so that it can be stored on the history list. 
However it will not be executed. In other words, the effect is the same as 
though the user had typed cdntrol-E at exactly the right instant. 



Control-U can be typed at any point, even in the middle of an atom; it 
simply sets an internal flag checked by lispxread . 

Control-U also works for calls to readline , i.e., for line commands. 
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valueof 



is an nlambda function 
a particular event 
(VALUEOF -F00 -2). 



for obtaining the value of 
t, e.g. (VALUEOF -1),^ 



The value of an event consisting of several 
operations is a list of the values for each of the 
individual operations. 



iVote.- the value field of a history entry is initialized to bell i ' control-G) . 
Thus a value of bell indicates that the corresponding operation did not 
complete, i.e. was aborted or caused an error (or else returned bell). 



prompting 



is a flag which when set to T causes the current 
event number to be printed before each : and » 
prompt characters. See description of promptchar , 
page 22.51 . 

prompting is initially MIL. 



archivefn 



allows the user to specify events 
automatically archived. 



to be 



When archivefn is set to T, and an event is about to drop off the end of the 
history list and be forgotten, archivefn is called giving it as its first 
argument the input portion of the event, and as its second argument, the entire 
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Although the input for valueof is entered on the history list before 
valueof is called, valueof[ -1 ] still refers to the value of the expression 
immediately before the valueof input, because valueof effectively backs the 
history list up one entry when it retrieves the specified event. 
Similarly, (VALUEOF F00) will find the first event before this one that 
contains a F00. 
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event/ 4 If archivefn returns T, the event is archived. For example, some 
users like to keep a record of all calls to load > Defining archivefn as: 
(LAMBDA (X Y) (EQ (CAR X) (QUOTE LOAD))) will accomplish this. Note that 
archivefn must be both set and defined. archivefn is initially NIL and 
undef ined. 

a * * 

lispxmacros provides a macro facility for lispx . 

lispxnacros allows the user to define his own lispx commands. It is a list of 
elements of the form (command def). Whenever command appears as the first 
expression on a line in a lispx input, the variable lispxline is bound to the 
rest of the line, the event is recorded on the history list, and def is 
evaluated. Similarly, whenever command appears as car of a form in a lispx 
input, the variable lispxline is bound to cdr of the form, the event recorded, 
ancl 1§I * s evaluated. (See page 22.61 for an example of a lispxmacro ) . 
RETRIEVE, BEFORE, and AFTER are implemented as lispxmacros . In addition in 
INTERLISP-10, LISP, SNDMSG, TECO, and EXEC are lispxmacros which perform the 
corresponding calls to subsys (section 21), and CONTIN is a lispxmacro which 
performs (SUBSYS T). Finally, SY and DIR are lispxmacros which perform the 
EXEC, SYSTAT, and DIRECTORY commands respectively. DIR can be given argumonts, 
e .g. , DIR *.SAV;«, 

lispxhistorymacros provides a macro facility for history commands. 

lispxhistorymacros allows the user to define his own history commands* The 



In case archivefn needs to examine the value of the event, its side 
effects, etc. See page 22.44 for discussion of the format of history 
lists. 
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format of lispxhistorymacros is the same as that of lispxmacros , except that 
the result of evaluating def is treated as a list of expressions to bo unread, 
exactly as though the expressions had been retrieved by a REDO command, or 
computed by a USE command. 

a a a 

lispxuserfn provides a way for a user function to process 

selected inputs. 

When lispxuserfn is set to T, it is applied to all inputs not recognized as 
one of the commands described above. If lispxuserfn decides to handle this 
input, it simply processes it (the event was already stored on the history list 
before lispxuserfn was called), sets lispxvalue to the value for the event, and 
returns T. lispx will then know not to call eval or apply , and will simply 
store lispxvalue into the value slot for the event, and print it. If 
lispxuserfn returns NIL, lispx proceeds by calling eval or apply in the usual 
way . Thus by appropriately defining (and setting) lispxuserfn , the user can 
with a minimum of effort incorporate the features of the programmer *s assistant 
into his own executive (actually it is the other way around). 



35 See page 22.17 for discussion of implementation of REDO, USE, and FIX. 

3G 

Like archivefn, lispxuserfn must be both set and defined. 
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The following output illustrates such a coupling 
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**SETQ( ALTFORM (MAPCONC NASDIC (F/L (GETP X 'ALTFORMS] 

=NASDICT 

(AL26 BE7 C05G C057 CO60 C13 H3 MN54 NA22 SC46 S34 TI44) 
**( GIVE ME LINES CONTAINING COBALT) 
SAMPLE PHASE CONSTIT. CONTENT 
S10002 OVERALL C056 40.0 



C13 
H3 

MN54 



8.8 

314.0 

28 



UNIT 
DPM/KG 
DEL 

DPM/KG 



**GETP( COBALT ALTFORMS) 

(C056 C057 CO60 C13 H3 MN54 NA22 SC46 S34 T144) 

*»UNDO MAPCONC 
SETQ UNDONE. 
ft *REDO GETP 
(C056 C057 CO60) 
**REDO COBALT 
SAMPLE PHASE 



S10002 
S10003 



OVERALL 
OVERALL 



CONSTIT. 
C057 
CO 



C056 
C057 
CO60 

**USE MANGANESE FOR COBALT 



CONTENT 
40.0 
15.0 
14.1 
43.0 
43.0 
1.0 



UNIT 
DPM/KG 



DPM/KG 



CITATION 
D70-237 
D70-228 



CITATION 

D70-237 

D70-203 

D70-216 

D70-237 

D70-241 



CI] 



[2] 
TAG 
0 
0 



[3] 

[4] 

[5] 

[6] 
TAG 
0 
0 

0 
0 



The user is running under his own executive program which accepts requests in 
the form of sentences, which it first parses and then executes. The user first 
'innocently' computes a list of all ALTERNATIVE - FORMS for the elements in his 
system [1]. He then inputs a request in sentence format [2] expecting to see 
under the column CONSTIT. only cobalt, CO, or its alternate forms, C056, C057, 
or CO00. Seeing C13, H3, and NN54, he aborts the output, and checks the 
property ALTFORMS for COBALT [3]. The appearance of C13, H3, MN54 , he aborts 
the output, and checks the property ALTFORMS for COBALT [3]. The appearance of 
C13, H3, MM54 et al, remind him that the mapconc is destructive, and that in 
the process of making a list of the ALTFORMS, he has inadvertently strung them 
all together. Recovering from this situation would require him to individually 
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The output is from the Lunar Sciences Natural Language Information System 
being developed for the NASA Manned Spacecraft Center by William A. Woods 
of Bolt Beranek and Newman Inc., Cambridge, Mass. 
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examine and correct the ALTFORMs for each element in his dictionary, a tedious 
process. Instead, he can simply UNDO MAPCONC, [4] check to make sure the 
ALTFORN has been corrected [5], then redo his original request [6] and 
continue. The UNDO is possible because the first input was executed by lispx ; 
the (GIVE. ME LINES CONTAINING COBALT) is possible because the user defined 
lispxuserfn appropriately; and the REDO and USE are possible because the 
(GIVE ME LINES CONTAINING COBALT) was stored on the history list before it was 
transmitted to lispxuserfn and the user's parsing program, 

lispxuserfn is a function of two arguments, x and line , where x is the first 
expression typed, and line the rest of the line, as read by readline (see page 
22.47). For example, if the user types F00(A B C), x=F00, and line=((A B C)); 
if the user types (F00 A B C), x=(FOO A B C), and line sNIL; and if the user 
types FOO ABC, x=FOO and Iine s(A B C). 

Thus in the above example, lispxuserfn would be defined as: 

[LAMBDA (X LINE) 
(COND 

( (AND (NULL LINE) 
(LISTP X)) 
(SETQ LISPXVALUE (PARSE X)) 
T] 

Note that since lispxuserfn is called for each input (except for p. a. 
commands), it can also be used to monitor some condition or gather statistics. 

ft & ft. 

In addition to saving inputs and values, lispx saves most system messages on 
the history list, e.g. FILE CREATED (fn REDEFINED), (var RESET), output of 
TIME, BREAKDOWN, STORAGE, DWIN messages, etc. When printhistory prints the 
event, this output is replicated. This facility is implemented via the 
functions lispxprint , lispxprinl , lispxprinZ, lispxspaces , lispxterpri , and 
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lispxtab. In addition to performing the corresponding output operation, those 
functions store an appropriate expression on the history event under tho 
property *LISPXPRINT* . 39 This expression is used by pr in thi story to reproduce 
the output . 



In addition to the above features, lispx checks to see if car or cdr of NIL or 
car of T have been clobbered, and if so, restores them and prints a message. 
Lispx also performs spelling corrections using lispxcoms , a list of its 
commands, as a spelling list whenever it is given an unbound atom or undefined 
function, i.e. before attempting to evaluate the input. *° 

22.6 Undoing 

The UNDO capability of the programmer's assistant is implemented by requiring 
that each operation that is to be undoable be responsible itself for saving on 
the history list enough information to enable reversal of its side effects. In 
other words, the assistant does not 'know 1 when it is about to perform a 
destructive operation, i.e. it is not constantly checking or anticipating. 
Instead, it simply executes operations, and any undoable changes that occur are 



In fact, all six of these functions have the same definition. When called, 
this function looks back on the stack to see what name it was called. by, 
and determines what to do. Thus, if the user wanted to make any other 
output function, e.g. printdef , record its MOVD( LISPXPRINT LXSPXPRINTDEF ) , 
and then use lispxprintdef for printdef . (This will work only for 
functions of three or fewer arguments.) 

unless lispxprintf lg is NIL. 

lispx is also responsible for rebinding helpclock, used by breakcheck , 
Section 16, for computing the amount of time spent in a computation, in 
order to determine whether to go into a break if and when an error occurs. 
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automatically saved on the history list by the responsible function. The 
operation of UNDOing, which involves recovering the saved information and 
performing the corresponding inverses, works the same way, so that the user can 
UNDO an UNDO, and UNDO that etc. 

At each point, until the user specifically requests an operation to be undone, 
the assistant does not know, or care, whether information has been saved to 
enable the undoing. Only when the user attempts to undo an operation does the 
assistant check to see whether any information has been saved. If none has 
been saved, and the user has specifically named the event he wants undone, the 
assistant types NOTHING SAVED. (When the user simply types UNDO, the assistant 
searches for the last undoable event, ingnoring events already undone as well 
as UNDO operations themselves.) 

This implementation minimises the overhead for undoing. Only those operations 
which actually make changes are affected, and the overhead is small: two or 
three cells of storage for saving the information, and an extra function call. 
However, even this small price may be too expensive if the operation is 
sufficiently primitive and repetitive, i.e. if the extra overhead may seriously 

AO 

degrade the overall performance of the program. Hence not every destructive 
operation in a program should necessarily be undoable; the programmer must be 
allowed to decide each case individually. 



When the number of changes that have been saved exceeds the value of 
^undosaves (initially set to 50), the user is asked if he wants to continue 
saving the undo information for this event. The purpose of this feature is 
to avoid tying up large quantities of storage for operations that will 
never need to be undone. The interaction is handled by the same routines 
used by DWIN, so that the input buffers are first saved and cleared, the 
message typed, then the system waits dwimwait seconds, and if there is no 
response, assumes the default answer, which in this case is NO. Finally 
the input buffers are restored. See page 22.56 for details. 



The rest of the discussion applies only to lispx ; the editor handles 
undoing itself in a slightly different fashion, as described on page 
22.61 . 
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Therefore for each primitive destructive operation, we have implemented two 
separate functions, one which always saves information, i.e. is always 
undoable, and one which does not, e.g. / rplaca and rplaca , /put and put . In 
the various system packages, the appropriate function is used. For example. 
break uses /putd and /remprop so as to be undoable, and DWIM uses /rplaca and 
/rplacd , when it makes a correction. 4 ^ Similarly the user can simply use the 
corresponding / function if he wants to make a destructive operation in his own 
program undoable. When the / function is called, it will save the undo 
information in the current event on the history list. 

However, all operations that are typed in to lispx are made undoable, simply by 
substituting the corresponding / function for any destructive function 
throughout the input.* 0 For example, on page 22.8, wheh the user typed 
(MAPCOf4C NASDIC (F/L ...)) it was ( /MAPCONC NASDIC (F/L .«.))■ that was 
evaluated. Since the system cannot know whether efficiency and overhead are 
serious considerations for the execution of an expression in a user program, 
the user must decide, e.g. call /mapconc if he wants the operation undoable . 
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The 'slash 1 functions currently implemented are /addprop ,, /attach , /closer , 
/drenove , /dreverse , /dsubst , /Iconc , /mapcon , /mapconc , /movd , /ncon c , 
/ nconcl , /put , /putd , /putdq , /puthash , /putl , /remprop , /rplaca , /rplacd , 
/rplnode , /rplnode2 , /set , /seta , /setd , and /tconc . Mote that /setq and 
/setqq are not included. If the user wants a set operation undoable in his 
program, he must see /set , or /rplaca . 

The effects of the following functions are always undoable (regardless of 
whether or not they are typed in): def ine , def ineq , def c (used to give a 
function a compiled code definition), def list , load , savedef , uri save dof , 
break , unbreak , rebreak , trace , breakin , unbreakin , changename, edi t f ns , 
editf , editv , editp , edite , editl, esubst , advise , unadvise , readvise , plus 
any changes caused by DWIM. 

Since there is no /setq , setq' s appearing in type-in are handled specially 
by substituting a call to saveset , page 22.43. 

The substitution is performed by the function lispx/ , described on page 
22.58. 
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However, expressions that are typed-in rarely involve iterations or lengthy 
computations directly. Therefore, if all primitive destructive functions that 
are immediately contained in a type-in are made undoable, there will rarely be 
a significant loss of efficiency. Thus lispx scans all user input before 
evaluating it, and substitutes the corresponding undoable function for all 
primitive destructive functions. Obviously with a more sophisticated analysis 
of both user input and user programs, the decision concerning which operations 
to make undoable could be better advised. However, we have found the 
configuration described here to be a very satisfactory one. The user pays a 
very small price for being able to undo what he types in, and if he wishes to 
protect himself from malfunctioning in his own programs, he can have his 
program specifically call undoable functions, or go into testmode as described 
next. 



Testmode 



Because of efficiency considerations, the user may not want certain functions 
undoable after his program becomes operational . However, while debugging ho 
may find it desirable to protect himself against a program running wild, by 
making primitive destructive operations undoable. The function testmode 
provides this capability by temporarily making everything undoable. 



testmode[ f lg] testmode[Tl redefines all primitive destructive 

functions with their corresponding undoable 
versions and sets testmodef lg to T. tcstmodef ] 
restores the original definitions, and sets 
testmodeflg to NIL. 
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i.e. the 1 slash 1 functions; see footnote on page 22.40. 
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testmode will have no effect on compiled mapconc 's, since they compile open 
with frplacd 's. 
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Note that setq 1 s are not undoable, even in testmode . To make the corresponding 
operation undoable in testmode , set or rplaca should be used. 

Undoing Out of Order 

/rplaca and /rplacd operate by saving the pointer that is to be changed and its 
original contents (i.e. /rplaca saves car and /rplacd saves cdr ) . Undoing 
/rplaca and /rplacd simply restores the pointer. Thus, if the user types 
(RPLACA FOO 1), followed by (RPLACA F00 2), then undoes both events by undoing 
the most recent event first, then undoing the older event, FOO will be restored 
to its state before either rplaca operated. However if the user undoes the 
first event, then the second event, (CAR FOO) will be 1, since this is what was 
in car of FOO before (RPLACA FOO 2) was executed. Similarly, if the user 
performs (fiCONCl FOO 1) then (NC0NC1 FOO 2), undoing just (NCONC1 FOO 1 ) will 
remove both 1 and 2 from FOO. The problem in both cases is that the two 
operations are not 'independent.' In general, operations are always independent 
if they affect different lists or different sublists of the same list.^ 9 
Undoing in reverse order of execution, or undoing independent operations, is 
always guaranteed to do the 'right 1 thing. However, undoing dopendont 
operations out of order may not always have the predicted effect. 
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Property list operations, (i.e. put, addprop and remprop) are handled 
specially so that they are always independent, even when they affect the 
sane property list. For example, if the user types PUT( FOO FIE 1 FUM1) then 
PUT(FOO FIE2 FUM2 ) , then undoes the first event, the FIE2 property will 
remain, even though CDR(FOO) may have been NIL at the time the first event 
was executed. 
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Saveset 



Seta's are made undoable on type in by substituting a call to snvcsot 
(described in detail on page 22.55), whenever setq is the name of the function 
to be applied, or car of the form to be evaluated. In addition to saving 
enough information on the history list to enable undoing, saveset operates in a 
manner analogous to savedef when it resets a top level value, i.e. when it 
changes a top level binding from a value other than NOBIND to a new value that 
is not equal to the old one. In this case, saveset saves the old value of the 
variable being set on the variable's property list under the property VALUE, 
and prints the message (variable RESET). The old value can be restored via the 
function unset , which also saves the current value (but does not print a 
message). Thus unset can be used to flip back and forth between two values. 

rpaq and rpaqq are implemented via calls to saveset . Thus old values will be 

saved and messages printed for any variables that are reset as the result of 
5 i 

loading a file . Calls to set and setqq appearing in type in are also 
converted to appropriate calls to saveset . 

For top level variables, saveset also adds the variable to the appropriate 
spelling list, thereby noticing variables set in files via rpaq or rpaqq , as 
well as those set via type in. 



Of course, UNDO can be used as long as the event containing this call to 
saveset is still active. Mote however that the old value will remain on 
the property list, and therefore be recoverable via unset , even after the 
original event has been forgotten. 



To complete the analogy with def ine , saveset will not save old values on 
property lists if dfnf lg =T, e.g. when load is called with second argument 
T, (however, the call to saveset will still be undoable,) and when 
dfnf lg =ALLPROP, the value is stored directly on the property list under 
property VALUE (the latter applies only to calls from rpaqq and rpaq ) . 
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22.7 Format and Use of the History List 



There are currently two history lists, lispxhistory and edithistory . Both 
history lists have the same format, and in fact, each use the same function, 
historysave , for recording events, and the same set of functions for 
implementing commands that refer to the history list, e.g. historyf inri , 
printhistory , undosave , etc. 

Each history list is a list of the form (1 event# size mod), where 1 is tho 
list of events with the most recent event first, event# is the event number for 
the most recent event on 1, size is the size of the time-slice, i.e. tho 
maximum length of 1, and mod is the highest possible event number (see footnote 
on page 22.8). lispxhistory and edithistory are both initialized to 
(NIL 0 30 100). Setting lispxhistory or edithistory to NIL is permitted, and 
simply disables all history features, i.e. lispxhistory and edithistory act 
like flags as well as repositories of events. 

Each individual event on 1 is a list of the form (input id value . props), 
where input is the input sequence for the event, as described on page 22.17-2-0, 
id the prompt character, e.g. V, », 53 and value is the value of the event, 
and is initialized to bell. 54 
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A third history list, archivelst , is used when events are archived, as 
described on page 22.27. It too uses the same format. 

id is one of the arguments to lispx and to historysave . A user can call 
lisp x giving it any prompt character he wishes (except for *, since in 
certain cases, lispx must use the value of id to tell whether or not it was 
called from the editor.) For example, on page 22.36, the user's prompt 
character was ** . 

On edithistory , this field is used to save the side effects of each 
command. 
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props is a property list, i.e. of the form (property value property value - - ) . 
props can be used to associate arbitrary information with a particular event. 
Currently, the properties SIDE, "GROUP*, *HISTORY«, «PRINT», USE-ARGS, . ..ARGS, 
®ERROR*, and *LISPXPRINT« are being used. The value of property SIDE is a list 
of the side effects of the event. (See discussion of undosave , page 22.56, 
and undolispx , page 22.59). The *HISTORY« and *GROUP« properties are used for 
commands that reexecute previous events, i.e. REDO, RETRY, USE, and FIX. 

The value of the ^HISTORY* 2 property is the history command itself, i.e. what 
the user actually typed, e.g. REDO FROM F, and is used by the ?? command for 
printing the event. The value of the property ^PRIMT* 5 is also for use by the 
?? command, when special formatting is required, for example, in printing 
events corresponding to the break commands OK, GO, EVAL, and ?=. USE-ARGS and 
. ..ARGS are used to save the arguments and expression for the corresponding 
history command. «ERROR» is used by the S command. ^LISPXPRINT* is used to 
record calls to lispxprint , lispxprinl , et al, See page 22.37. 

When lispx is given an input, it calls historysave to record the input in a new 
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event. Normally, historysave returns as its value cddr of the new event, i.e. 
car of its value is the value field of the event, lispx binds lispxhist to the 
value of historysave , so that when the operation has completed, lispx knows 
where to store the value, namely in car of lispxhist lispxhist also provides 
access to the property list for the current event. For example, the / 
functions are all implemented to call undosave , which simply adds the 
corresponding information to lispxhist under the property SIDE, or if there is 
no property SIDE, creates one, and then adds the information. 



The commands ??, FORGET, TYPE-AHEAD, SBUFS, and ARCHIVE are executed 
immediately, and are not recorded on the history list . 



Note that by the time it completes, the operation may no longer correspond 
to the most recent event on the history list. For example, all inputs 
typed to a lower break will appear later on the history list. 
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After binding lispxhist , lispx executes the input, stores its value in car of 
lispxhist , prints the value, and returns. 

When the input is a REDO, RETRY, USE, or FIX command, the procedure is 

similar, except that the event is also given a "GROUP* property, initially NIL , 
and- a. "HISTORY* property, and lispx simply unreads the input and returns. Vhon 
the input is 'reread', it is historysave , not lispx , that notices this fact, 
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and finds the event from which the input originally came. \ historysave then 
adds a new (value . props) entry to the "GROUP* property for this event, and 
returns this entry as the 'new event.' lispx then proceeds exactly as when its 
input was typed directly, i.e. it binds lispxhist to the value of historysave , 
executes the input, stores the value in car of lispxhist , prints the value, and 
returns. In fact, lispx never notices whether it is working on freshly typed 
input, or input that was reread. Similarly, undosave will store undo 
information on lispxhist under the property SIDE the same as always, and does 
not know or care that lispxhist is not the entire event, but one of the 
elements of the "GROUP* property. Thus when the event is finished, its entry 
will look like: 

(input id value "HISTORY* command "GROUP* ((valuel SIDE sidel) 

(value2 SIDE side2) 

...)) 68 

This implementation removes the burden from the function calling historysave of 
distinguishing between new input and reexecution of input whose history entry 



If historysave cannot find the event, for example if a user program unreads 
the input directly, and not via a history command, historysave proceeds as 
though the input were typed. 



In this case, the value field is not being used; valueof instead collects 
each of the values from the "GROUP* property, i.e. returns 
mapcar[ get[ event ; "GROUP"]; CAR]. Similarly/undo operates by collecting the 
SIDE properties from each of the elements of the "GROUP" property, and then 
undoing them in reverse order. 
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has already been set up. 



22.8 lispx and readline 

lispx is called with the first expression typed on a line as its first 
argument, lispxx . 

If this is not a list, lispx always does a readline , and treats lispxx plus the 
line as the input for the event, and stores it accordingly on the history 
list.^ Then it decides what to do with the input, i.e. if it is not recognized 
as a command P a lispxmacro , or is processed by lispxuserfn , call eval or 
apply , 61 readline normally is terminated either by (1) a carriage return that 
is not preceeded by a space, or (2) a list that is terminated by a ]» or (3) an 
unmatched ) or ] f which is not included in the line. However, when called from 
lispx , readline operates differently in two respects: 

(1) If the line consists of a single ) or ], readline returns (NIL) 
instead of NIL, i.e. the ) or ] is included in the line. This permits 
the user to type F00) or F00], meaning call the function* FOO with no 
arguments, as opposed to F00> (FOOcarriage-return) 0 meaning evaluate 
the variable FOO. 

(2) If the first expression on the line is a list that is not preceded by 
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Although we have not yet done so, this implementation , i.e. keeping the 
various 1 sub-events 1 separate with respect to values and properties, also 
permits constructing commands for operating on just one of the sub-events. 

If lispxx is a list car of which is LAMBDA or NLAMBDA, lispx calls 
lispxread to obtain the arguments. 



If the input consists of one expression, eval is called; if two, apply ; if 
more than two, the entire line is treated as a single form and eval is 
called. 
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any spaces, the list terminates the line regardless of whether or not 
it is terminated by ]. This permits the user to type EDITF(FOO) as a 
single input. 

Note that if any spaces are inserted between the atom and the left parentheses 
or bracket, readline will assume that the list does not terminate the line. 
This is to enable the user to type a line command such as USE (FOO) FOR. FOO. In 
this case, a carriage return will be typed after (FOO) followed by M . " as 
described in Section 14. Therefore, if the user accidentally puts an extra 
space between a function and its arguments, he will have to complete the input 
with another carriage return, e.g. 

HEDITFJFOO) 

EDIT 

ft 

22,9 Functions 

lispxC lispxx; lispxid; iispxxmacros ; lispxxuserfn]^ 2 

lispx is like eval / apply . It carries out a single 
computation, and returns its value. The first 
argument, lispxx is the result of a single call to 
lispxread . lispx will call readline , if necessary 
as described on page 22.47. lispx prints the 
value of the computation, as well as saving the 



lispxid corresponds to id on page 22.44. Lispx also has a fifth argument, 
lispxf lg , which is used by the E command in the editor. 
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input and value on lispxhistory . 



If lispxx is a history command, lispx executes the 
command, and returns bell as its value. 
If the value of the fourth argument, 1 ispxxjnacros , 
is not NIL, it is used as the lispx macros, 
otherwise the top level value of lispxinacros is 
used. If the value of the fifth argument, 
lispxxuserfn , is not NIL, it is used as 
lispxuserfn . In this case, it is not necessary to 
both set and define lispxuserfn as described on 
page 22.35. 

The overhead for a call to lispx (in INTERLISP-10 ) is approximately 1? 
milliseconds, of which 12 milliseconds are spent in maintaining the spelling 
lists. In other words, in INTERLISP, the user pays 17 more milliseconds for 
each eval or apply input over a conventional LISP executive, in order to enable 
the features described in this chapter. 

userexec[ lispxid ;lispxxmaeros; lispxxuserfn 3 

repeatedly calls lispx under errorset protection 
specifying lispxxmacros and lispxxuserfn , and 
using lispxid (or «* if lispxid sNIL) as a prompt 
character. Userexec is exited via the lispxmacro 
OK, or else with a retf rom . 



Note that the history is not one of the arguments to lispx , i.e. the editor 
must bind (reset) lispxhistory to edithistory before calling lispx to carry 
out a history command. — ^ — - - — 

L ispx will continue to operate as an eval / apply function if lispxhistory is 
NIL. Only those functions and commands that involve the history list will 
be affected. 
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lispxread[ f ile ;rdtbl] is a generalised read . If readbufsNIL, lispxread 

performs read[f ilejrdtbl], which it returns as its 
value. (If the user types control-U during tho 
call to read , lispxread calls the editor and 
returns the edited value,) 

If readbuf is not NIL, lispxread /reads 4 the next 

expression on readbuf , i.e. essentially returns 

(PR0G1 (CAR READBUF) 

(SETQ READBUF (CDR READBUF ) ) ) . 

readline , described in Section 14, also uses this generalized notion of 
reading. When readbuf is not NIL, readline 'reads' expressions from readbuf 
until it either reaches the end of readbuf , or until it reads a pseudo-carriago 
return (see page 22.18). In both cases, it returns a list of the expressions 
it has 'read 1 . (The pseudo-carriage return is not Included 1n the 11st.) 

When readbuf is not NIL, both lispxread and readline actually obtain their 
input by performing (APPLY* LISPXREADFN FILE), where lispxreadfn is initially 
set to READ. Thus, if the user wants lispx , the editor, break, et al to do 
their reading via a different input function, e.g. uread , he simply sets 
lispxreadfn to the name of that function (or an appropriate LAMBDA expression). 

lispxreadpt f lg] is a generalized readp . If flg sT, lispxreadp 

returns T if there is any input waiting to be 
•read 1 , a la lispxread . If f lg =NIL, lispxroadp 
returns T only if there is any input waiting to be 



Except that pseudo-carriage returns, as represented by the value of 
histstrO , are ignored, i.e. skipped. Lispxread also sets rereadf l g to NIL 
when it reads via read , and sets rereadf lg to the value of readbuf when 
rereading. 



22.50 



'read 1 on this line. In both cases, leading spaces 
are ignored, i.e. skipped over with readc P so that 
if only spaces have been typed, lispxreadp will 
return NIL. 

lispxunreadC 1st] unreads 1st, a list of expressions to be read. If 

readbuf is not NIL, lispxunread attaches 1st at 
the front of readbuf 0 separating it from the rest 
of readbuf with a (HISTSTRO 0). The definition of 
lispxunread is: 

(LISPXUNREAD 
[ LAMBDA (LST) 

(SETQ READBUF (COND 
( (MULL READBUF) 
LST) 

(T (APPEND LST (CONS HISTSTRO 

READBUF ] ) 

promptchar[ id;f lg;hist] prints the prompt character id. 

promptchar will not print anything when the next 
input will be 'reread 8 , i.e. readbuf is not MIL. 
promptchar will also not print when readp[]-T 9 
unless fig is T. 

Thus the editor calls promptchar with f ig aNXL so that extra * ' s are not printed 
when the user types several commands on one line. However, evalgt calls 
promptchar with flcpT since it always wants the printed (except when 
\ 1 rereading 1 ) . 

Finally, if prompts Ig is T and hist is not NIL „ 
J promptchar prints the current event number (of 

hist ) before printing id. 
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llspxeval[ lispxform;lispxid] evaluates lispxform (using eval ) the same as 

though it were typed in to lispx , i.e. the event 
is recorded, and the evaluation is made undoablo 
by substituting the slash functions for the 
corresponding destructive functions, as described 
on page 22.40. llspxeval returns the value of the 
form, but does not print it. 

h is torysave[ history; id; input 1 ;input2;inpu t3; props] 

records one event on history . If inputl is not 
NIL, the input is of the form 
(inputl input2 . input3). If inputl is NIL, and 
input2 is not NIL, the input is of the form 
(input2 . inputs). Otherwise* the input is just 
input3 . 

historysave creates a new event with the 
corresponding input, jld, value field initialized 
to bell, and props . If the history has reached 
its full size, the last event is removed and 
cannibalized. 

The value of historysave is cddr of the event. 
However, if rereadf Ig is not NIL, and is a tail of 
the input of the most recent event on the history 
list, and this event contains a *GROUP* property, 
historysave does not create a new event, but 
simply adds a (bell . props) entry to the *GROUP* 
property and returns that entry. See discussion 
on page 22.46. 
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lispxf ind[ history; line; type; backup] 

line is an event specification, type specifies the 
format of the value to be returned by lispxf ind , 
and can be either ENTRY, ENTRIES. COPY, COPIES , 
INPUT, or REDO, lispxf ind parses line , and uses 
historyf ind to find the corresponding events. 
lispxfind then assembles and returns the 
appropriate structure. 

lispxf ind incorporates the following special features: 

(1) if backup =T, lispxfind interprets line in the context of the history list 
before the current event was added. This feature is used, for example, by 
valueof , so that (VALUEOF -1) will not refer to the valueof event itself; 

(2) if line sNXL and the last event is an UNDO, the next to the last event is 
taken. This permits the user to type UNDO followed by REDO or USE; 

(3) lispxfind recognises @@, and substitutes archivelst for history (see page 
22.14); and 

(4) lispxf ind recognizes @, and retrieves the corresponding event(s) from the 
property list of the atom following @ (see page 22.14)* 

historyf ind[ 1st ; index ;mod;x;y] 

searches 1st and returns the tails of 1st 
beginning with the event corresponding to x. 1st , 
index , and mod are as described on page 22.44. 
x is an event address, as described on page 
22.11-14, e.g. (43), (-1), (FOOFIE), 
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(LOAD «• FOO), etc. -If historyf ind cannot find x, 
it generates an error. 

entry#[hist ;x] hist is a history list, i.e. of the form described 

on page 22.44. x is one of the events on hist , 
i.e. (MEHB X (CAR HIST)) is true. The value of 
entry# is the event number for x. 

valueof[x] is an nlambda, nospread function for obtaining the 

value of the event specified by x» e.g. 
(VALUEOF -1), (VALUEOF LOAD 1), etc. valueof 
returns a list of the corresponding values if x 
specifies a multiple event. 

changeslice[n;historyi 66 changes time-slice for history to n. If history 

is NIL, changes both edithiatory and lispxhistory . 

Note: the effect of increasing a time-slice is gradual: the history list is 
simply allowed to grow to the corresponding length before any events are 
forgotten. Decreasing a time-slice will immediately remove a sufficient number 
of the older events to bring the history list down to the proper size. 
However, changeslice is undoable, so that these events are (temporarily) 
recoverable. Thus if the user wants to recover the storage associated with 
these events without waiting n more events for the changeslice event to be 
forgotten, he must perform a FORGET command. 



If ^ is given, the event address is the list difference between x and y 9 
e.g. x=(FOO FIE AND \ -1), £=(AND \ -t) is equivalent to 

x=(FOO FIE), X*UIL. 

changeslice has a third argument used by the system for undoing a 
changeslice . 
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save set [ name ; value ; topf Ig ;f lg] 

an undoable set. (see page 22.43). save set scans 
the pushdown list looking for the last binding of 
name , sets name to value , and returns value . 

If the binding changed was a top level binding, 
name is added to spellingsS (see Section 17). 
Furthermore, if the old value was not N0B1ND, and 
was also not equal to the new value, savesot calls 
the file package to update the necessary file 
records. Then, if dfnf lg is not equal to T a 
saveset prints (name RESET), and saves the old 
value on the property list of name , under the 
property VALUE. If Hc^NOPRINT, saveset saves the 
old value, but does not print the message. This 
option is used by unset . 

If topf lg sT, saveset operates as above except that 
it does not scan the pushdown list but goes right 
to name's value cell, e.g. rpaqq[x;y] is simply 
saveset[x;y;T]. When topf lg is T, and dfnf lg is 
ALLPROP and the old value was not NOBIND, savesot 
simply stores value on the property list of name 
under the property VALUE, and returns value . This 
option is used for loading files without 
disturbing the current value of variables (see 
Section 14). 

if flgsNOSAVE, saveset does not save the old value 
on the property list, nor does it add name to 
spellings3 . However, the call to saveset is still 
undoable. This option is used by /set . 
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unset[name] if name does not contain a property VALUE, unset 

generates an error. Otherwise unset calls savoset 
with name , the property value, topf lg=T, and 
f IgsNOPRINT. 

undosave[undoform] if lispxhist is not NIL (see discussion on page 

22.45), and get[ lispxhist ;SIDE] is not equal to 
NOSAVE, undosave adds undoform to the value of the 
property SIDE on lispxhist , creating a SIDE 
property if one does not already exist. The form 
of undoform is (fn . args),^ 5 i.e. undoform is 
undone by performing 

apply[car[ undoform] ;Cdr[ undoform]]. For example , 
if the definition of F00 is def , /putd[FOO;newdef ] 
will cause a call undosave with 
undoform *(/PUTD F00 def). 

car of the SIDE property is the number of 
'undosaves 1 , i.e. length of cdr of the SIDE 
property, which is the list of undoforms . Each 
call to undosave increments this count, and adds 
undoform to the front of the list, i.e. just after 
the count. When the count reaches the value of 
#undosaves (initially 50), undosave prints a 
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Undosave has a second optional argument, histentry , which can be used to 
specify lispxhist directly, saving the time to look it up. If both 
histentry and lispxhist are NIL, undosave is a NOP. 

Except for /rplnode , as described below. 

#undosaves sNIL is equivalent to #undosavess infinity. 
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message asking the user if he wants to continue 
saving. If the user answers NO or defaults, 
undosave makes NOSAVE be the value of the property 
SIDE, which disables any further saving for this 
event. If the user answers YES, undosave changes 
the count to -1 , which is then never incremented, 
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and continues saving. 

/rplnode[x;a;d] Undoably performs rplaca[x;a] and rplacdt x;d] . 

Value is x. Generates an error, ILLEGAL ARG , if 
x is not a list. The principle advantage of 
/rplnode is that when x is a list, /rplnode saves 
its undo information as 

cons[ x; cons[ car[x];cdr[x] ]], i.e. 
(x originalcar . originalcdr ) , and therefore 
requires only 3 cells of storage, instead of the 8 
that would be required for a /rplaca and a /rplacd 
that saved their information as described 
earlier. 7i 

/rplnode has a BLKLIBRARYDEF . 
7rplnode2[x;y3 same as /rplnodetx;carf y3 ;cdrfy33 • 



7Q 

load initializes the count on SIDE to -1, so that regardless of the value 
of *undosaves , no message will be printed, and the load will be undoable. 
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Actually, /rplaca and /rplacd also use this format for saving their undo 
information when their first arguments are lists. However, if both a 
/rplaca and /rplacd are to be performed, it is still more efficient to use 
/rplnode (3 cells versus 6 cells). 
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Note: for consistency, there are definitions for both rplnode and rplnode2 , 
although there primary reason for existence is the undoable versions/ 



new/fn[fn] After the user has defined /fn, new/fn performs 

the necessary housekeeping operations to make fn 
be undoable. 

For example, the user could define /radix as 

( LAMBDA (X) (UNDOSAVE (LIST (QUOTE /RADIX) (RADIX X))) and then perform 
new/fn[radix], and radix would then be undoable when typed in or in testmode. 

lispx/[x;fn;vars] performs the substitution of / functions for 

destructive functions. If fn is not NIL, it is 
the name of a function, and x is its argument 
list. If fn is NIL, x is a form. In both cases, 
lispx/ returns x with the appropriate 
substitutions. Vars is a list of bound variables 
(optional). 

lispx/ incorporates information about the syntax 
and semantics of INTBRLISP expressions. For 
example, it does not bother to make undoable 
operations involving variables bound in x. It 
does not perform substitution inside of 
expressions car of which is NLAMBDA, i.e. has 
argtype 1 or 3 (unless car of the form has the 
property INFO value EVAL, as described in section 
20). For example, (BREAK PUTD) typed to lispx, 
will break on putd , not /putd . Similarly, 
substitution should be performed in the arguments 
for functions like mapc , rptq , etc . , since these 
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contain expressions that will be evaluated or 
applied. For example, if the user types 
mapc[(F001 F002 F003);PUTD] the putd must be 
replaced by /putd . 

undolispx[line] line is an event specification, undolispx is the 

function that executes UNDO commands by calling 
undolispxl on the appropriate entry(s). 

undolispxi[event ;flg] undoes one event. The value of undolispxl is NIL 

if there is nothing to be undone. If the event is 
already undone, undolispxl prints ALREADY UNDONE 

7? 

and returns T. Otherwise, undolispxl undoes the 
event, prints a message, e.g. SETQ UNDONE , and 
returns T. 

Undoing an event consists of mapping down (cdr of) the property value for SIDE, 
and for each element, applying car to cdr , and then marking the event undone by 
attaching (with / attach ) a NIL to the front of its SIDE property. Note that 
the undoing of each element on the SIDE property will usually cause undosavos 
to be added to the current lispxhist , thereby enabling the effects of 
undolispxl to be undone. 

undonlsetq[ f orm] is an nlambda function similar to nlsetq . 

undonlsetq evaluates form , and if no error occurs 
during the evaluation, returns list[eval[form]] 



If flg =T and the event is already undone, or is an undo command, undol is pxl 
takes no action and returns NIL. Undolispx uses this option to search for 
the last event to undo. Thus when line sNIL, undolispx simply searches 
history until it finds an event for which undolispxl returns T, i.e. 
undolispx performs (SOME (CDAR LISPXHISTORY) (F/L (UNDOLISPX! X T))) 
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and passes the undo information from form (if any) 
upwards. If an error does occur, the value of 
undonlsetq is NIL, and any changes made by / 
functions during the evaluation of form are 
undone. 



undonlsetq compiles open. 

undonlsetq will operate even if lispxhistory or 
lispxhist are NIL, or if #undosaves is or has been 
exceeded for this event. 

Mote that undonlsetq provides a limited form of backtracking. 

printh is tory[ history ;line;skipfn; novalues] 

line is an event specification. printhistory 
prints the events on history specif led by line, 
e.g. (-1 THRU -10). skipfn is an (optional) 
functional argument that is applied to each event 
before printing. If its value is true, the event 
is skipped, i.e. not printed. If novalues sT, or 
novalues applied to the corresponding event is 
true, the value is not printed.^ 
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Actually, undonlsetq does not rebind lispxhist , so that any undo 
information is stored directly on the history event, exactly as though 
there were no undonlsetq . Instead, undonlsetq simply marks the state of 
the undo information when it starts, so that if an error occurs, it can 
then know how much to undo. The purpose of this is so that if the user 
control-D's out of the undonlsetq , the event is still undoable. 

For example, novalues is T when printing events on edithistory . 
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For example, the following lispxmacro will define ??' as a command for printing 
the history list while skipping all 'large events 1 and not printing any values. 



(??' (PRINTHISTORY LISPXHISTORY LISPXLINE 
(FUNCTION (LAMBDA (X) 

(I6REATERP (COUNT (CAR X)) 5))) 
T)) 



22.10 The Editor and the Assistant 

As mentioned earlier,, all of the remarks concerning 'the assistant' apply 
equally well to user interactions with evalqt , break or the editor. The 
differences between the editor's implementation of these features and that of 
lispx are mostly obvious or inconsequential. However* for completeness, this 
section discusses the editor's implementation of the programmer's assistant. 

The editor uses promptchar to print its prompt character, and lispxread, 
lispxreadp, and readline for obtaining inputs. When the editor is given an 
input, it calls historysave to record the input in a new event on its history 
list, edithistory . Edithistory follows the same conventions and format as 
lispxh istory . However, since edit commands have no value, the editor uses the 
value field for saving side effects, rather than storing them under the 
property SIDE. 

The editor processes DO, IE, !F, and !N commands itself, since lispx does not 
recognize these commands. The editor also processes UNDO itself, as described 



Except that the atomic commands OK, STOP, SAVE, P, ?, PP and E are not 

recorded. In addition, number commands are grouped together in a single 

event. For example, 3 3 -i is considered as one command for changing 
position. 
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below. All other history commands are simply given to lispx for execution, 

after first binding (resetting) lispxhistory to edithistory . The editor also 
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calls lispx when given an E command as described in Section 9. 

The major implementation difference between the editor and lispx occurs in 
undoing. Edithistory is a list of only the last n commands, where n is the 
value of the time-slice. However the editor provides for undoing all changes 
made in a single editing session, even if that session consisted of more than n 
edit commands. Therefore, the editor saves undo information independently of 
the edithistory on a list call undolst , (although it also stores each entry on 
undolst in the field of the corresponding event on edithistory . ) Thus, the 
commands UNDO, ! UNDO, and UNBLOCK, are not dependent on edithistory ,^ i.e. 
UNDO specifies undoing the last command on undolst , even if that event no 
longer appears on edithistory . The only interaction between UNDO and the 
history list occurs when the user types UNDO followed by an event 
specification. In this case, the editor calls lispxf ind to find the event, and 
then undoes the corresponding entry on undolst . Thus the user can only undo a 
specified command within the scope of the edithistory . (Note that this is also 
the only way UNDO commands themselves can be undone, that is, by using the 
history feature, to specify the corresponding event, e.g. UNDO UNDO.) 



as indicated by their appearance on historycoms, a list of the history 
commands. editdef ault interrogates historycoms before attempting spoiling 
correction. (All of the commands on historycoms are also on editcomsa and 
editcomsl so that they can be corrected if misspelled in the editor.) Thus 
if the user defines a lispxmacro and wishes it to operate in the editor as 
well, he need simply add it to historycoms . For example, RETRIEVE is 
implemented as a lispxmacro and works equally well in lispx and the editor. 



In this case, the editor uses the fifth argument to lispx , lispxflg , to 
specify that any history commands are to be executed by a recursive call to 
lispx , rather than by unreading. For example, if the user types E REDO in 
the editor, he wants the last event on lispxhistory processed as 1 ispx 
input, and not to be unread and processed by the editor. 



and in fact will work if edithlstory =NIL, or even in a system which does 
not contain lispx at all. — 



77 
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The implementation of the actual undoing is similar to the way it is done in 
lispx : each command that makes a change in the structure being edited does so 
via a function that records the change on a variable. After the command has 
completed, this variable contains a list of all the pointers that have been 
changed and their original contents. Undoing that command simply involves 
mapping down that list and restoring the pointers. 

22.11 Statistics 

The programmer's assistant keeps various statistics about system usage, e.g. 
number of lispx inputs, number of undo saves, number of calls to editor, number 
of edit commands, number of p. a. commands, cpu time, console time, et al. 
These can be viewed via the function lispxstats . 

lispxstats[ ] prints statistics. 

The user can add his own statistics to the lispx statistics via the function 
addstats . 

addstats[statlst] no spread, nlambda. Statist is q list of elements 

of the form (statistic-name . message), e.g. 
(EOITCALLS CALLS TO EDITOR) (UNDOSTATS CHANGES 
UNDONE), etc. statistic-name is set to the cell 
in an unboxed array, where the corresponding 
statistic will be stored. This statistic can then 
be incremented by lispxwatch . 

lispxwatch[stat ;n] increments stat by n (or 1 if nsNIL). lispxwatch 

has a BLKLIBRARYDEF. 



22.63 



The user can save his statistics for loading into a new system by performing 
MAKEFILE(DUMPSTATS). After the file DUMPSTATS is loaded, the statistics printed 
by lispxstats will be the same as those that would be printed following the 
makefile . 

22.12 Greeting and User Initialization 

Many of the features of INTERLISP are parameterized to allow the user to adjust 
the system to his or her own tastes. Among the more commonly adjusted 
parameters are prompt^f Ig , dwlmwait . changeslice , #rpars , lowercase , archivef n , 
#undosaves , f ltfmt , etc. In addition, the user can modify the action of system 
functions in ways not specifically provided for by using advise (Section 19). 

In order to encourage this procedure, and to make it as painless and automatic 

as possible, the p. a. includes a facility for a user-defined profile. When 

INTERLISP is first run, it obtains and evaluates a list of user-specified 
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expressions for initializing the system, and the p. a. prints a greeting, 
e.g., "HELLO, WARREN." or "GOOD AFTERNOON, DANNY. \ etc. 

Greeting (i.e., the initialization) is undoable, and is stored as a separate 
event on the history list. The user can also specifically invoke the greeting 
operation via the function greet , for example, if he wishes to effect another 
user's initialization. 

greet[name;f lg] performs greeting for user whose username is name , or 

if namesNIL, for login name (see username and 



In INTERLISP-10, a specially formatted file on the LISP directory contains 

the initializations for all users. This file is indexed into using the 

user's usernumber as a key. The expressions (if any) found there are then 
evaluated. 
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usernumber , Section 21), i.e., when INTERLXSP first 
starts up, it performs greet[]. Before greet porforms 
the indicated initialization, it first undoos the 
effects of the previous greeting. If f Ig =T , greet 
also resets the counters for the various statistics 
reported by lispxstats (page 22.63). 

greet also sets the variable username to the name for which the greeting was 
performed. Sysin is advised to compare username with username[]. If they are 
the same, sysin prints heraldstring , followed by the greeting message 

Of 

Ohterwise, sysin prints a message alerting the user. For example, if user 
HARTLEY performs a sysin of a sysout made by user GOODWIN, the following 
message is printed: 

*«**ATTENTXON USER HARTLEY: 

THIS SYSOUT IS INITIALIZED FOR USER GOODWIN. 

TO REINITIALIZE, TYPE GREET() 

INTERLISP-10 Implementation of Greeting 

greet operates off the file <LISP>USERNAMEFILE . To change an existing 
initialization, or create a new one, a new <LISP>USERNAMEFILE must be written. 
This is accomplished by loading the file <LISP>USERNAMES, editing usernamolst , 
and then performing makeusernames[ ], which will create new versions of both 



The side effects of the greeting operation are stored on a global variable 
as well as the history list, thus enabling the previous greeting to be 
undone even if it is no longer on the history list. 



sysout first checks the value of the variable sysoutgag , initially NIL. If 
s ysout gag is T, no message is printed following a sysin . If sysoutg ag is a 
list, it will be evaluated in lieu of printing a message. For example, tho 
user can use this option to print his own message. 
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USERNAMEf ILE. and USERNAMES. (Note that the person performing this operation 
must therefore either be connected to the LISP directory, or have write access 
to it. ) 

usernamelst is a list of elements of the form (username firstname T . forms), 
e.g.. (TEITELMAN WARREN T (CHANGESLICE 100) (SETQ DWIMWAIT 5)). cadr of tho 
list is used in the greeting message, cdddr is a list of forms that arc 
evaluated . 

usernanelst can be edited just like any other list, e .g . , with edttv. The file 
USERNAMEFILE, created by makeusernames , contains usernamelst along with an 
index block which contains for each user on usernamelst the addres;s in the file 
(i.e., byte position) of the start of his entry, greet then simply does an 
sf ptr and a read . 

If usernamelst contains an element for which the username is NIL, i.e., an 
element of the form (NIL . forms), this is interpreted to mean that f orms are 
evaluated regardless of user name. This feature can be used to "patch" an 
IMTERLISP system when a bug is found, or to change some default for INTERLISP 
at a particular site, e.g., turn off DWIM, perform lowercase[T], etc. 
Individual user initialization will still be performed following this system 
initialization . 
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SECTION 23' 
CLISP - CONVERSATIONAL LISP 



23.1 Introduction 

The syntax of LISP is very simple, in the sense that it can be described 
concisely, but not in the sense that LISP programs are easy to read or write! 
This simplicity of syntax is achieved by, and at the expense of, extensive use 
of explicit structuring, namely grouping through parenthesesisation . Unlike 
many languages, there are no reserved words in LISP such as IF,, THEN, AND, OR, 
FOR, DO, BEGIN, END, etc., nor reserved characters like /, a , etc. 

This eliminates entirely the need for parsers and precedence rules in the LISP 
interpreter and compiler, and thereby makes program manipulation of LISP 
programs straightforward. In other words, a program that "looks at" other LISP 
programs does not need to incorporate a lot of syntactic information. For 
example, a LISP interpreter can be written in one or two pages of LISP code 
([McCl], pp. 70-71). It is for this reason that LISP is by far the most 
suitable, and frequently used, programming language for writing programs that 
deal with other programs as data, e.g., programs that analyse, modify, or 
construct other programs. 



CLISP was designed and implemented by W. Teitelman. It is discussed in 
[Tei5]. 

except for parentheses (and period), which are used for indicating 
structure, and space and end-of-line, which are used for delimiting 
identif iers. 
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However, it is precisely this same simplicity of syntax that makes LISP 
programs difficult to read and write (especially for beginners). 'Pushing 
down 1 is something programs do very well, and people do poorly. As an example, 
consider the following two 'equivalent 1 sentences: 

"The rat that the cat that the dog that I owned chased caught ate the 
cheese." 

versus 

"I own the dog that chased the cat that caught the rat that ate the 
cheese . " 

Natural language contains many linguistic devices such as that illustrated in 
the second sentence above for minimising embedding, because embedded sentences 
are more difficult to grasp and understand than equivalent non-embedded ones 
(even if the latter sentences are somewhat longer). Similarly, most high level 
programming languages offer syntactic devices for reducing apparent depth and 
complexity of a program: the reserved words and infix operators used in ALGOL- 
like languages simultaneously delimit operands and operations, and also convey 
meaning to the programmer. They are far more intuitive than parentheses. In 
fact, since LISP uses parentheses (i.e. lists) for almost all syntactic forms, 
there is very little information contained in the parentheses for the person 
reading a LISP program, and so the parentheses tend mostly to be ignored: the 
meaning of a particular LISP expression for people is found almost entirely in 
the words, not in the structure. For example, the following expression 

(COND (EQ N 0) 1) (T TIMES N FACTORIAL ((SUB1 N) ) ) 

is recognizable as FACTORIAL even though there are five misplaced or missing 
parentheses. Grouping words together in parentheses is done more for LISP ' s 
benefit, than for the programmer's. 

CLISP is designed to make INTERLISP programs easier to read and write by 
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permitting the user to employ various infix operators, IF-THEN-ELSE statements, 
FOR-DO-WHILE-UNLESS-FROM-TO-etc. expressions, which are automatically convertod 
to equivalent INTERLISP expressions when they are first interpreted. For 
example, FACTORIAL could be written in CLISP: 

(IF N=0 THEN 1 ELSE N«(FACTORIAL N-l)) 

Note that this expression would become an equivalent COND after it had boon 
interpreted once, so that programs that might have to analyze or otherwise 
process this expression could take advantage of the simple syntax. 

There have been similar efforts in other LISP systems, most notably the MLISP 
language at Stanford [Smil]. CLISP differs from these in that it does not 
attempt to replace the LISP syntax so much as to augment it. In fact, one of 
the principal criteria in the design of CLISP was that users be able to freely 
intermix LISP and CLISP without having to identify which is which. Users can 
write programs, or type in expressions for evaluation, in LISP, CLISP, or a 
mixture of both. In this way, users do not have to learn a whole new language 
and syntax in order to be able to use selected facilities of CLISP when and 
where they find them useful. 

CLISP is implemented via the error correction machinery in INTERLISP (see 
Section 17). Thus, any expression that is well-formed from INTERLISP* s 
standpoint will never be seen by CLISP (i.e., if the user defined a function 
IF, he would effectively turn off that part of CLISP). This means that 
interpreted programs that do not use CLISP constructs do not pay for its 
availability by slower execution time. In fact, the INTERLISP interpreter does 
not 'know 1 about CLISP at all. It operates as before, and when an erroneous 
form is encountered, the interpreter calls an error routine which in turn 
invokes the Do-What-I-Mean (DWIM) analyzer which contains CLISP. If the 
expression in question turns out to be a CLISP construct, the equivalent 
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IMTERLISP form' is returned to the interpreter. In addition,, the original CLISP 
expression, is modified so that it becomes the correctly translated IMTERLISP 
form. In this way, the analysis and translation are done only once. 

Integrating CLISP into the IMTERLISP system (instead of, for example, 
implementing it as a separate preprocessor) makes possible Do-What-I-Nean 
features for CLISP constructs as well as for pure LISP expressions. For 
example, if the user has defined a function named GET-PARENT, GLISP would know 
not to attempt to interpret the form (GET-PARENT) as an arithmetic infix 
operation. (Actually, CLISP would never get to see this form, since it does 
not contain any errors.) If the user mistakenly writes (GET-PRAENT) , CLISP 
would know he meant (GET-PARENT) , and not (DIFFERENCE GET PRAENT), by using the 
information that PRAENT is not the name of a variable, and that GET-PARENT is 
the name of a user function whose spelling is "very close" to that of 
GET-PRAENT . Similarly, by using information about the program's environment not 
readily available to a preprocessor, CLISP can successfully resolve the 
following sorts of ambiguities: 

1) (LIST X*FACT N) , where FACT is the name of a variable, means 
(LIST (X*FACT) N) . 

2) (LIST X**FACT N) , where FACT is not the name of a variable but instead is 
the name of a function, means (LIST X*(FACT N) ) , i.e. , N is FACT'S 
argument . 

3) (LIST X*FACT(N)), FACT the name of a function (and not the name of a 
variable), means (LIST X«(FACT N))v 

4) cases ( 1), (2) and (3) with FACT misspelled! 

The f irst expression is correct both from the standpoint of CLISP syntax and 
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semantics and the change would be made without the user being notified. In the 
other cases, the user would be informed or consulted about what was taking 
place. For example, to take an extreme case, suppose the expression 
(LIST X*FCCT N) were encountered, where there was both a function named FACT 
and a variable named FCT. The user would first be asked if FCCT were a 
misspelling of FCT. If he said YES, the expression would be interpreted as 
(LIST (X*FCT) H). 3 If he said NO, the user would be asked if FCCT were a 
misspelling of FACT, i.e., if he intended X«FCCT N to mean X*( FACT N ) . If he 
said YES to this question, the indicated transformation would be performed. If 
he said MO, the system would then ask if X ft FCCT should be treated as CL1SP, 
since FCCT is not the name of a (bound) variable.^ If he said YES, the 
expression would be transformed, if WO, it would be left alone, i.e., as 
(LIST X^FCCT N). Mote that we have not even considered the case where X*FCCT is 
itself a misspelling of a variable name, e.g., a variable named XFCT (as with 
GET-PRAENT) . This sort of transformation would be considered after the user 
said MO to X*FCCT N -> X^(FACT N) . The graph of the possible interpretations 
for (LIST X*FCCT N) where FCT and XFCT are the names of variables, and FACT is 
the name of a function, is shown in Figure 23-1 below. 



Through this discussion, we speak of CLISP or DWIN asking the user. 
Actually, if the expression in question was typed in by the user for 
immediate execution, the user is simply informed of the transformation, on 
the grounds that the user would prefer an occasional misinterpretation 
rather than being continuously bothered, especially since he can always 
retype what he intended if a mistake occurs, and ask the programmer's 
assistant to UNDO the effects of the mistaken operations if necessary. For 
transformations on expressions in user programs, the user can inform CLISP 
whether he wishes to operate in CAUTIOUS or TRUSTING mode. In the formor 
case (most typical) the user will be asked to approve transformations, in 
the latter, CLISP will operate as it does on type-in, i.e., perform the 
transformation after informing the user. 



This question is important because many INTERLISP users already have 
programs that employ identifiers containing CLISP operators. Thus, if 
CLISP encounters the expression A/B in a context where either A or B are 
not the names of variables, it will ask the user if A/B is intended to be 
CLISP, in case the user really does have a free variable named A/B. 
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FCCT- >FCT ? 




FIGURE 23-1 
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The final states for the various terminal nodes shown in the graph are: 



1 : 


(LIST 


(TIMES X FCT) N) 


2: 


(LIST 


(TIMES X (FACT N ) ) ) 


3: 


(LIST 


XFCT N) 


4: 


(LIST 


(TIMES X FCCT) N) 


5: 


(LIST 


X"FCCT N) 



CLISP can also handle parentheses errors caused by typing 8 or 9 for 1 (' or 
•)'. (On most terminals, 8 and 9 are the lower case characters for •(' and 
i.e., 1 ( 1 and '8' appear on the same key, as do , ) 1 and '9'.) For 
example, if the user writes N*8FACT0RIAL N-l , the parentheses error can be 
detected and fixed before the infix operator * is converted to the INTERL1SP 
function TIMES. CLISP is able to distinguish this situation from cases like 
N*8*X meaning (TIMES H 8 X), or N*8X, where 8X is the name of a variable, again 
by using information about the programming environment. In fact, by 
integrating CLISP with DWIM, CLISP has been made sufficiently tolerant of 
errors that almost everything can be misspelled! For example, CLISP can 
successfully translate the definition of FACTORIAL: 

(IFF N=0 THENN1 ESLE N*8FACTT0RIALNN-1 ) 

to the corresponding COND, while making 5 spelling corrections and fixing the 
parenthesis error. 5 

This sort of robustness prevails throughout CLISP. For example, the iterative 



CLISP also contains a facility for converting from 1NTERLISP back to CLISP, 
so that after running the above incorrect definition of FACTORIAL, the user 
could 'CLISPIFY 1 the now correct LISP version to obtain 
(IF N=0 THEN 1 ELSE N*( FACTORIAL N-l)), 
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statement permits the user to say things like:^ 

FOR OLD X FROM H TO N DO (PRINT X) WHILE (PRIMEP X) 

However, the user can also write OLD ( X*-M ) , (OLD X*-M) , (OLD (X*»M)), permute the 
order of the operators, e.g., DO PRINT X TO N FOR OLD X-M WHILE PRIMEP X, omit 
either or both sets of parentheses, misspell any pr all of the operators FOR, 
OLD, FROM, TO, DO, or WHILE, or leave out the word DO entirely! And, of 
course, he can also misspell PRINT, PRIMEP, M or N! 7 

CLISP is well integrated into the INITERLISP system. For example, the above 
iterative statement translates into an equivalent INTERLISP form using PROG, 
COND, GO, etc.^ When the interpreter subsequently encounters this CLISP 
expression, it automatically obtains and evaluates the translation.^ Similarly, 
the compiler "knows" to compile the translated form. However* if the user 
PRETTYPRINTs his program, at the corresponding point in his function, 
PRETTYPRINT "knows" to print the original CLISP. Similarly, when the user 
edits his program, the editor keeps the translation invisible to the user. If 



ft 

This expression should be self explanatory, except possibly for tho 
operator OLD, which says X is to be the variable of iteration, i.e., tho 
one to be stepped from N to M, but X is not to be rebound. Thus when this 
loop finishes execution, X will be equal to N+l. 

■7 

In this example, the only thing the user could not misspell is the first X, 
since it specifies the name of the variable of iteration. The other two 
instances of X could be misspelled. 



8 



9 



(PROG NIL 

(SETO X M) 
S$LP(COND 

( (OR (IGREATERP X N) 

(NOT (PRIMEP X))) 
(RETURN))) 
(PRINT X) 
(SETO X (ADD1 X)) 
(GO SSLP)) 



See page 23.31, for discussion of how translations are stored. 
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the user modifies the CUSP, the translation is automatically discarded and 
recomputed the next time the expression is evaluated. 

In short, CLISP is not a language at all, but rather a system. It plays a role 
analagous to that of the programmer's assistant (Section 22). Whereas the 
programmer's assistant is an invisible intermediary agent between the user's 
console requests and the INTERLISP executive, CUSP sits between the user's 
programs and the INTERLISP interpreter. 

Only a small effort has been devoted to defining the core syntax of CUSP. 
Instead, most of the effort has been concentrated on providing a facility which 
•makes sense' out of the input expressions using context information as well as 
built-in and acquired information about user and system programs. It has boon 
said that communication is based on the intention of the speaker to produce an 
effect in the recipient. CUSP operates under the assumption that what the 
user said was intended to represent a meaningful operation, and therefore tries 
very hard to make sense out of it. The motivation behind CUSP is not to 
provide the user with many different ways of saying the same thing, but to 
enable him to worry less about the syntactic aspects of his communication with 
the system. In other words, it gives the user a new degree of freedom by 
permitting him to concentrate more on the problem at hand, rather than on 
translation into a formal and unambiguous language. 

23.2 CUSP Syntax 

Throughout CUSP, a non-atomic form, i.e., a list, can always be substituted 
for a variable, and vice versa, without changing the interpretation. For 
example, if the value of (F00 X) is A, and the value of (FIE Y) is B, then 
(LIST (FOO X) + (FIE Y) ) has the same value as (LIST A+B). Note that the first 
expression consists of a list of four elements: the atom 'LIST*, the list 
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1 (POO X)', the atom and the list * (FIE X) 8 , whereas the second expression, 

(LIST A+B) , consists of a list of only two elements: the atom 'LIST 1 and tho 
atom »A+B'. Since (LIST (F00 X)*(FIE Y)) is indistinguishable from 
(LIST (FOO X)_*_(FIE Y)) because spaces before or after parentheses have no 
effect on the INTERLISP READ program,*** to be consistent; extra spaces have no 
effect on atomic operands either. In other words, CLISP will treat 
(LIST A+_B), (LIST A_*B), and (LIST A^B) the same as (LIST A*B). 

23.3 Infix Operators 

CLISP recognizes the arithmetic infix operators -, w , /» and t. These are 
converted to IPLUS, IDIFFERENCE (or in the case of unary minus, IMINUS), 
ITIMES, IQUOTIENT, .and .EXPT. * J The usual precedence rules apply (although these 
can be easily changed by the user), i.e., * has higher precedence than + so 
that A+B*C is the same as A*(B*C), and both * and / are lower than t so that 
2*X?2 is the same as 2*(Xt2). Operators of the same precedence group from left 
to right, e.g., A/B/C is equivalent to (A/B)/C. Minus is binary whenever 
possible, i.e., except when it is the first operator in a list, as in (-A) or 



CLISP does not use its own special READ program because this would require 
the user to explicitly identify CLISP expressions, instead of being able to 
intermix INTERLISP and CLISP. 



The I in IPLUS denotes integer arithmetic, i.e., IPLUS converts its 
arguments to integers, and returns an integer value. INTERLISP also 
contains floating point arithmetic functions as well as mixed arithmetic 
functions (see Section 13). Floating point arithmetic functions are used 
in the translation if one or both of the operands are themselves floating 
point numbers, e.g. X+1.5 translates as (FPLUS X 1.5). In addition, CLISP 
contains a facility for declaring which type of arithmetic is to be used, 
either by making a global declaration, or by separate declarations about 
individual functions or variables. See section on declarations, page 
23.35. 



The complete order of precedence for CLISP operators is given in 
Figure 23-2, page 23.15. 
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(-A), or when it immediately follows another operator, as in A*-B.* 3 * 4 



Mote that grouping with parentheses can always be used to override the normal 
precedence grouping, or when the user is not sure how a particular expression 
will parse. 



IS 

CLISP also recognizes as infix operators s, GT, IT, GE, and LE, as well as 
various predicates, e.g., MEMBER, AND, OR, EQUAL, etc. 16 AMD is higher than OR, 
e.g., (X OR Y AND Z) is the same as (X OR (Y AND Z)), and both AND and OR are 
lower than the other infix operators, e.g., (X AND Y EQUAL Z) is the same as 
(X AND (Y EQUAL Z)). All of the infix predicates have lower precedence than 
IMTERLISP forms, i.e., (FOO X GT FIE Y) is the same as ((FOO X) GT (FIE Y)), 
since it is far more common to apply a predicate to two forms, than to use a 
Boolean as an argument to a function, e.g. (FOO (X GT (FIE Y))). However, 
again* the user can easily change this. 



Mote that only single character operators, e.g. *», =, etc., can appear in 
the interior oj an atom. All other operators must be set ofj from identifiers 



13 



14 



15 



16 



There are some do-what- I-mean features associated with Unary minus, as in 
(LIST -X Y). See section on operation, page 23.68. 

Mote that + in front of a number will disappear when the number is read, 
e.g., (FOO X *2) is indistinguishable from (FOO X 2) . This means that 
(FOO X 4-2) will not be interpreted as CLISP, or be converted to 
(FOO (IPLUS X 2)). Similarly, (FOO X -2) will not be interpreted the same 
as (FOO X-2). To circumvent this, always type a space between the «■ or - 
and a number if an infix operator is intended, e.g., write (FOO X * 2). 

Greater Than, Less Than, Greater than or Equal to, and Less than or Equal 
to, respectively, GT, LT, GE, and LE ""are all affected by the same 
declarations as «• and ®, with the initial default to use IGREATERP and 
ILESSP. 

Currently the complete list is MEMBER, MEMB, FMEMB, ILESSP, IGREATERP, 
LESSP, GREATERP, FGTP, EQ, NEQ, EQP, EQUAL, OR, and AND. Mow infix 
operators can be easily added, as described in the section on CLISP 
internal conventions, page 23.72. Spelling correction on misspelled infix 
operators is peformed using clispinf ixsplst as a spelling list. 
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with spaces . For example, XLTY will not be recognized as CUSP. 17 



: is an infix operator used in CLISP for extracting substructures from lists, i5 
e.g., X:3 specifies the 3rd element of X, (FOO Y) : :2 specifies the second tail 
of (FOO Y), i.e. , (CDDR (FOO Y)), and Z: 1:2 is the second element of the first 
element of Z, or (CADAR Z). Negative numbers may be used to indicate position 
counting from the end of a list, e.g., X:-l is the last element of X, or 
(CAR (LAST X)) t X::-l is the last tail, i.e., (LAST X). ip 



is used to indicate assignment, e.g., X«-Y translates to (SETQ X Y) . In 



17 



18 



19 



20 



21 



In some cases, DWIM will be able to diagnose this situation as a run-on 
spelling error, in which case after the atom is split apart, CLISP will be 
able to perform the indicated transformation. 

The record facility, page 23.50, provides another way of extracting 
substructures by allowing the user to assign names to the various parts of 
the structure and then retrieve from or store into the corresponding 
structure by name. The pattern match facility, page 23.38, also can be 
used to extract substructure. : is also used to indicate both record and 
pattern match operations. 

The interpretation of negative numbers can be explained neatly in terms of 
edit commands: :-n returns what would be the current expression after 
executing the command -n, and ::-n returns what would be the current 
expression after executing -n followed by UP. 

If x does not have a value, and is not the name of one of the bound 
variables of the function in which it appears, spelling correction is 
attempted. However, since this may simply be a case of assigning an 
initial value to a new free variable, DWIM will always ask for approval 
before making the correction. 

Mote that an atom of the form X*Y, appearing at the top level of a PROG, 
will not be recognized as an assignment statement because it will be 
interpreted as a PROG label by the INTERLISP interpreter, and therefore 
will not cause an error, so DWIM and CLISP will never get to see it. 
Instead, one must write (X*Y). 
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conjunction with : and ::, <> can also be used to perform a more general type of 
assignment, namely one involving structure modification. For example, X:2*-Y 
means make the second element of X be Y, in INTERLXSP terms 
(RPLACA (CDR X) Y). 22 23 Negative numbers can also be used, e.g., X:-2-Y. 24r *• 
is also used to indicate assignment in record operations, page 23.50, and 
pattern match operations, page 23.38. 

has different precedence on the left from on the right. On the left,.*- is a 
"tight" operator, i.e., high precedence, so that A4B«-C is the same as A+(B*-C). 
On the right, *- has broader scope so that A*-B+C is the same as A*(B*C). 

On typein, S»-f orm ( alt-mode*-f orm) is equivalent to set the "last thing 
mentioned". For example, immediately after examining the value of 
LONGVARIABLENAME , the user could set it by typing $*• followed by a form. 



23.4 Prefix Operators 

CLISP recognizes 1 and - as prefix operators. ' means QUOTE when it is the 
first character in an identifier, and is ignored when it is used in the 
interior of an identifier. Thus, X='Y means (EQ X (QUOTE Y)), but X=CAN 1 T 
means (EQ X CAN 1 T) , not (EQ X CAN) followed by (QUOTE T). This enables users 



Mote that the value of this operation is the value of rplaca , which is the 
corresponding node. 

The user can indicate he wants /rplaca and /rplacd used (undoable version 
of rplaca and rplacd , see Section 22), or frplaca and f rplacd (fast 
versions of rplaca and rplacd , see Section 5), by means of declarations 
(page 23.35). The initial default is for rplaca and rplacd . 

which translates to (RPLACA (NLEFT X 2) Y). 

i.e. is equivalent to (SETQ lastword form). See Section 17. 
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to have variable and function names with ' in them (so long as the \ is not tho 

first character). 



Following all operators are ignored for the rest of the identifier, e.g., 
'*A means (QUOTE *A), and .'X«Y means (QUOTE X=Y), not (EQ (QUOTE X) Y) , 26 



On typein, *S (i.e. 'alt-mode) is equivalent to (QUOTE value -of- las tword) (sec 
Section 17). For example, after calling prettyprint on LONGFUNCTION, the usor 
could move its definition to FOO by typing (MOVD •$ 'F00). 27 

~ means NOT. * can negate a form, as in -(ASSOC X Y), or -X, or negate an 
infix operator, e.g., (A -GT B) is the same as (A LEQ B). Note that -A=B means 
(EQ (NOT A) B). 



26 



27 



To write (EQ (QUOTE X) Y), one writes Y=*X, or *X_=Y. This is one place 
where an extra space does make a difference. 

iVot (MOVD S 'F00), which would be equivalent to (MOVD LONGFUNCTION »FOO), 
and would (probably) cause a U.B.A. LONGFUNCTION error, nor MOVD(S FOO), 
which would actually move the definition of $ to FOO, since DWIM and the 
spelling corrector would never be invoked. 
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Order of Precedence of CL1SP operators 



o (left precedence) 
- (unary), - 

t 

a . / 

- (binary) 
o (right precedence) 

IMTERLISP forms 

LT, GT, EQUAL, MEMBER, etc. 

AND 

OR 

IF, THEM, ELSEIF 9 ELSE 
iterative statement operators 



Figure 23-2 



28 



29 



*- has a different left and right precedence, e.g., A+B*-C*D is the same as 
A+(B«-(C*D) ) . In other words, «■ has minimal scope on the left and maximal 
scope on the right. 

When - negates an operator, e.g., , -LT, the two operators are treated as 
a single operator whose precedence is that of the second operator. When - 
negates a function, e.g., (-F00 X Y), it negates the whole form, i.e., 
(-(F00 X Y) ) . 
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23.5 Co ns tructing Lists - the < , > operators ' 



Angle brackets are used in CLISP to indicate list construction. The appearance 
of a corresponds to a ■(■ and indicates that a list is to be constructed 
containing all the elements up to the corresponding , > l . For example, <A B <C» 
translates to (LIST A B (LIST C) ) . ! can be used to indicate that the next 
expression is to be inserted in the list as a segment, e.g., <A B ! C> 
translates to (CONS A (CONS B C)) and <! A ! B C> to (APPEND A B (LIST C)). !! 
is used to indicate that the next expression is to be inserted as a segment, 
and furthermore, all list structure to its right in the angle brackets is to be 
physically attached to it, e.g. , <!! A B> translates to (NC0NC1 A B), and 
<! !A !B !C> to (NCONC A (APPEND B C)). 31 32 Note that <, !, M , and > need not 
be separate atoms, for example, <A B ! C> may be written equally well as 
< A B ! C > . Also, arbitrary INTERLISP or CLISP forms may be used within angle 
brackets. For example, one can write <F00*( FIE X) ! Y> which translates to 
(CONS (SETQ F00 (FIE X) ) Y). CLISPIFY converts expressions in cons , list , 
append , nconc , nconcl , /nconc, and /nconcl into equivalent CLISP expressions 
using < , >, ! , and ! ! . 

Note: angle brackets differ from other CLISP operators in that they act more 
like brackets than operators. For example, <A B *C> translates to 
(LIST A B (QUOTE C)) even though following all operators are ignored for the 
rest of the identifier. 33 Note however that <A B r _C> D> is equivalent to 

The <,> operator was written by P.C. Jackson. 

31 Not (NCONC (APPEND A B) C), which would have the same value, but would 
attach C to B, and not attach either to A. 

op 

The user can indicate /nconc or /nconcl be used instead of nconc and nconcl 
by. declarations. 

33 

Only if a previous unmatched < has been seen, e.g. (PRINT * A>B ) will 
print the atom A>B. 
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(LIST A B (QUOTE C>) 0). 



23.6 IF, THEN , ELSE 

CLISP translates expressions employing IF | THEN | ELSE IF | ELSE into equivalent 
conditional expressions. The segment between IF|ELSEIF and the next THEN 
corresponds to the predicate of a COND clause, and the segment between THEN and 
the next ELSE | ELSEIF as the consequent s) . ELSE is the same as ELSE IF T THEN . 

IF, THEN, ELSE, and ELSEIF are of lower precedence than all infix and prefix 
operators, as well as INTERLISP forms, so that parentheses can be omitted 
between IF | ELSEIF , and THEN. 34 For example, (IF F00 X Y THEN --) is equivalent 
to (IF (FOO X Y) THEN --). 35 Similarly, CLISP treats (IF X THEN FOO X Y ELSE 
--) as equivalent to (IF X THEN (FOO X Y) ELSE --) because it does not 'make 
sense' to evaluate a variable for effect. In other words, even if FOO were 
also the name of a variable, (COND (X FOO X Y)) doesn't make sense. 
Essentially, CLISP determines whether the segment between THEN and the next 
ELSE | ELSEIF corresponds to one form or several and acts accordingly. 3 * 5 Thus , 
(IF THEN (FOO X) Y ELSE --) corresponds to a clause with two consequents. 
Similarly, (IF THEN F00*-X Y ELSE corresponds to a clause with two 



IF, THEN, ELSE, and ELSEIF can also be misspelled. Spelling correction is 
performed using clispifwordsplst as a spelling list. 

If FOO is the name of a variable, IF FOO THEN is translated as 
(COND (FOO —)) even if FOO is also the name of a function. If the 
functional interpretation is intended, FOO should be enclosed in 
parentheses, e.g., IF (FOO) THEN --. Similary for IF THEN FOO ELSEIF 

occasionally interacting with the user to resolve ambiguous cases. 
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consequents, and is equivalent to (IF THEN (FOO»X) Y ELSE --). 



23.7 Iterative Statements 

The following is an example of a CLISP iterative statement: 

(WHILE X«-(READ)-='STOP DO (PRINT (EVAL X))) 

This statement says "READ an expression and set X to it. If X is not equal to 
the atom STOP, then evaluate X, print the result, and iterate*" 35 

The i.s. (iterative statement) in its various forms permits the user to specify 
complicated iterative statements in a straightforward and visible manner. 
Rather than the user haying to perform the mental transformations to an 
equivalent INTERLISP ■ form using PROG, MAPC, MAPCAR, etc., the system does it 
for him. The goal was to provide a robust and tolerant facility which could 
"make sense" out of a wide class of iterative statements. Accordingly, the 
user should not feel obliged to read and understand in detail the description 
of each operator given below in order to use iterative statements. 

Currently, the following i.s. operators are implemented: FOR, BIND, OLD, IN, 
ON, FROM, TO, BY, WHEN, WHILE, UNTIL, REPEATWHILE, REPEATUNTIL, UNLESS, 
COLLECT, JOIN, DO, SUM, COUNT, ALWAYS, NEVER, THERE IS, AS, FIRST, FINALLY, 



To write the equivalent of a singleton cond clause, i.e., a clause with a 
predicate but no consequent, write either nothing following the THEN, or 
omit the THEN entirely, e.g., (IF (F00 X) THEN ELSEIF ~) or 
(IF (FOO X) ELSEIF --), meaning if (F00 X) is not NIL, it is the value of 
the cond . 

The statement translates to: 

(PROG (SSVAL) S$LP(COND ( ( EQ (SETQ X (READ) ) (QUOTE STOP) ) (RETURN SSVAL))) 
(PRINT (EVAL X) ) SSITERATE (GO SSLP)) 
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EACHTXME, Their function is explained below. New operators can be defined as 
described on page 23.29. Misspellings of operators are recognized and 
corrected. 5 ^ The order of appearance of operators is never important CLISP 
scans the entire statement before it begins to construct the equivalent 
INTERLISP form. 

DO form specifies what is. to be done at each iteration. DO with no 

other operator specifies an infinite loop. If some explicit 
or implicit terminating condition is specified, the value of 
the i.s. is NIL. Translate to MAPC or HAP whenever 
possible . 



COLLECT form like DO, except specifies that the value of form at each 

iteration is to be collected in a list, which is returned as 
• the value of the i.s. when it terminates. Translates to 
MAPCAR, MAPLIST or SUBSET whenever possible. 41 

JOIN form like D0 P except that the values are NCONCed. Translates to 

MAPCONC or MAPCON whenever possible. 42 



39 
40 



41 



42 



using the spelling list clispforwordsplst . 

DV/IM and CLISP are invoked on iterative statements because car of the i.s. 
is not the name of a function, and hence generates an error. If the user 
defines a function by the same name as an i.s. operator, e.g. WHILE, TO, 
etc., the operator will no longer have the CLISP interpretation when it 
appears as car of a form, although it will continue to be treated as an 
i.s. operator if it appears in the interior of an i.s. To alert the user, a 
warning message is printed, e.g. 

(WHILE DEFINED, THEREFORE DISABLED IN CLISP) . 

when COLLECT translates to a PROG, e.g. a WHILE operator appears in the 
iterative statement, the translation employs an open tconc using two 
pointers similar to that used by the compiler for compiling mapcar . 

/NCONC, /MAPCONC, and /MAPCON are used when the declaration UNDOABLE is in 
effect. 
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SUM form 



like DO, except specifies that the values of form at each 
iteration be added together and returned as the value of the 
i . s . , 

1+4+94-16*25 



e.g. (FOR I FROM 1 TO 5 SUM HZ) is equal to 
43 



COUNT pred 



like DO, except counts number of times that pred is true, 
and returns that count as its value. 



ALWAYS pred 



like DO, except returns T if the value of pred is non-NIL 
for all iterations (returns NIL as soon as the value of pred 
is NIL), e.g. (FOR X IN Y ALWAYS (ATOM X)) is the same as 
(EVERY Y (FUNCTION ATOM)). 



NEVER pred 



like ALWAYS, except returns T if the value of pred is never 
true, i.e. NEVER pred is the same as ALWAYS -pred. 



THEREIS pred returns the first value of the i.v. for which pred is 

non-NIL, e.g. (FOR X IN Y THEREIS NUMBERP) returns the 
first number in V, and is equivalent to 
(CAR (SOME Y (FUNCTION NUMBERP))). 44 

DO, COLLECT, JOIN, SUM, ALWAYS, NEVER, and THEREIS are examples of a certain 
kind of i.s. operator called an i .s.type . The i .s.type specifies what is to bo 
done at each iteration. Its operand is called the body of the iterative 



43 

iplus , f plus , or plus will be used for the translation depending on the 
declarations in effect. 

44 THEREIS returns the i.v. instead of the tail (as does the function some) in 
order to provide an interpretation consistent with statements such as 
(FOR I FROM 1 TO 10 THEREIS -.-),' where there is no tail. Note that 
(SOME Y (FUNCTION NUMBERP) ) is equivalent to 
(FOR X ON Y THEREIS (NUMBERP (CAR X))). 
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stateir<»nt. Each i.s. must have one and only one i .s.type . The function 
i.s. typ e, page 23.29, provides a means of defining additional i.s. type s. 

specifies the variable of iteration,, or i.v., which is usod 
in conjunction with IN, ON, FROM, TO P and BY. The variable 
is rebound for the scope of the i.s., except when modified 
by OLD as described below. 

vars a list of variables, e.g., FOR (X Y Z) IN The first 
variable is the i.v., the rest are dummy variables. See 
BIND below. 

indicates var is not to be rebound, e.g., 
(FOR OLD X FROM 1 TO N DO « UNTIL —),."' 

BIND var, vars used to specify dummy variables, e.g., FOR (X Y Z) IN is 

equivalent to FOR X BIND (Y 2) IN . BIND can be used 
without FOR. For example, in the i.s. shown on page 23.18, 
X could be made local by writing 

(BIND X WHILE X*-(READ)~= 'STOP. . . ) . 

Mote: FOR, OLD, and BIND variables can be initialized by using e.g., 
(FOR OLD (X«-form) BIND ( Y«-form) . . . ) . 

IN form specifies that the i.s. is to iterate down a list with the 

i.v, being reset to the corresponding element at each 
iteration. For example, FOR X IN V DO .-- corresponds to 
(MAPC Y (FUNCTION (LAMBDA (X) -'•)))• If no i.v. has been 
specified, a dummy is supplied, e.g., IN Y COLLECT CADR is 
equivalent to (MAPCAR Y (FUNCTION CADR)). 



FOR var 



FOR vars 



OLD var 
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ON form same as IN except that the i.v. is reset to tho 

corresponding tail at each iteration. Thus IN corresponds 
to MAPC, MAPCAR, and MAPCONC, while ON corresponds to MAP , 
MAPLIST, and MAPCON. 

IN OLD var specifies that the i.s. is to iterate down var , with var 

itself being reset to the corresponding tail at each 
iteration, e.g., after (FOR X IN OLD L DO --UNTIL 
finishes, L will be some tail of its original value. 

IN OLD (variform) same as IN OLD var, except var is first set to value of 

form . 

ON OLD var same as IN OLD var except the i.v. is reset to the current 

value of var at each iteration, instead of to car[var], 

ON OLD (variform) same as ON OLD var , except var is first set to value of 

form . 

WHEN pred provides a way of excepting certain iterations. For 

example, (FOR X IN Y COLLECT X WHEN NUMBERP X) collects only 
the elements of Y that are numbers. 

UNLESS pred same as WHEN except for the difference in sign, i.e., WHEN Z 

is the same as UNLESS -Z. 

WHILE pred provides a way of terminating the i.s. WHILE pred evaluates 

pred bejore each iteration, and if the value is NIL, exits. 

UNTIL pred Same as WHILE except for difference in sign, i.e., 

WHILE PRED is equivalent to UNTIL -PRED. 
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UNTIL n 



n a number, equivalent to UNTIL (i.v. GT n). 



REPEATWHILE pred same as WHILE except the test is performed after tho 

evalution of the body, but before the i.v, is reset for the 
next iteration. 

REPEATUNTIL pred/n same as UNTIL, except the test is performed after the 

evaluation of the body. 

FROM form is used to specify an initial value for a numerical i.v. 

The i.v. is automatically incremented by 1 after each 
iteration (unless BY is specified). If no i.v. has been 
specified, a dummy i.v. is supplied and initialized, e.g., 
(COLLECT SORT FROM 2 TO 5) returns (1.414 1.732 2.0 2.236). 

TO form is used to specify the final value for a numerical i.v. If 

FROM is not specified, the i.v. is initialized to 1. If no 
i.v. has been specified, a dummy i.v. is supplied and 
initialised. If BY is not specified, the i.v, is 
automatically incremented by 1 after each iteration. When 
the i.v. is definitely being incremented, i.e. either BY is 
not specified, or its operand is a positive number, the i.s. 
terminates when the i.v. exceeds the value of form (which 1s 
reevaluated each Iteration) e.g. 9 (FOR X FROM 1 TO 10 ••). 
is equivalent to (FOR X FROM 1 UNTIL (X GT 10) --). 



except when both the operands to TO and FROM are numbers, and TO' s operand 
is less than F ROM's operand, e.g. FROM 10 TO 1, in which case the i.v. is 
decremented by 1 after each iteration. In this case, the i.s. terminates 
when the i.v. becomes less than the value of form. 
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Similarly, when the i.v. is definitely being decremented the 
i.s. terminates when the i.v. becomes less than the value of 
form (see description of BY). 

BY x (with IN/ON) If IN or ON have been specified, the value of x determines 

the tail for the next iteration, which in turn determines 
the value for the i.v. as described earlier, i.e. the now 
i.v. is car of the tail for IN, the tail itself for ON. In 
conjunction with IN, the user can refer to the current tail 
within x by using the i.v. or the operand for IN/ON, e.g. 
(FOR Z IN L BY (CDDR Z) ...) or 
(FOR Z IN L BY (CDDR L) ...). At translation time, the name 
of the internal variable which holds the value of the 
current tail is substituted for the i.v. throughout x. For 
example, (FOR X IN Y BY (CDR (MEMB TOO (CDR X)>) COLLECT X) 
specifies that after each iteration, cdr of the current tail 
is to be searched for the atom FOO, and ( cdr of) this latter 
tail to be used for the next iteration. 

BY x (without IN/ON) If IN or ON have not been used, BY specifies how the 

i.v. itself is reset at each iteration. If FROM or TO have 
been specified, the i.v. is known to be numerical, so the 
new i.v. is computed by adding the value of x 
(which is reevaluated each iteration) to the current value 
of the i.v., e.g., (FOR N FROM 1 TO 10 BY 2 COLLECT N) makes 
a list of the first five odd numbers. 

If x is a positive number,^ the i.s, terminates when the 



x itself, not its value, which in general CLISP would have no way of 
knowing in advance. 
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value of the i.v. exceeds the value of TO's operand. If x 
is a negative number, the i.s. terminates when the value of 
the i.v. becomes less than TO f s operand, e.g. 
(FOR I FROM N TO M BY -2 UNTIL (I LT li) . ..). Otherwise, 
the terminating condition for each iteration depends on the 
value of x for that iteration: if x < 0, the test is whether 
the i.v. is less than TO's operand, if x > 0 the test is 
whether the i.v. exceeds TO's operand, otherwise if x=0, the 
i.s. terminates unconditionally.^ 



If FROM or TO have not been specified, the i.v. is simply 

reset to the value of x after each iteration, e.g. 

(FOR I FROM N BY 2 ...) is equivalent to 
(FOR I«-N BY (IPLUS 12)...). 



FIRST form form is evaluated once before the first iteration, e.g. 

(FOR X Y Z IN L FIRST (FOO Y Z)), and FOO could be used 
to initialize Y and Z. 



FINALLY form form is evaluated after the i.s. terminates. For example, 

(FOR X IN L BIND Y*0 DO (IF ATOM X THEN Y-Y*!) 
FINALLY (RETURN Y)) will return the number of atoms in L. 



EACHTIME form form is evaluated at the beginning of each iteration before, 

and regardless of, any testing. For example, consider (FOR I 
FROM 1 TO N DO (... (FOO I) ...) UNLESS (,. . (FOO I) ...) 
UNTIL (... (FOO I) ....))• The user might want to set a 



A temporary variable is used so that x is only evaluated once. However, 
code for TO's operand appears twice in"" the translation, even though it is 
evaluated only once. 
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temporary variable to the value of (F00 I) in order to avoid 
computing it three times each iteration. However, without 
knowing the translation, he would not know whether to put 
the assignment in the operand to DO, UNLESS, or UNTIL, i.e. 
which one would be executed first. He can avoid this 
problem by simply writing EACHTIME J-(FOO I). 

AS var is used to specify an iterative statement involving more 

than one iterative variable, e.g. 

(FOR X IN Y AS U IN V DO -«•) corresponds to map2c . The i.s. 
terminates when any of the terminating conditions are met, 
e.g. (FOR X IN Y AS I FROM I TO 10 COLLECT X) makes a list 
of the first ten elements of Y, or however many elements 
there are on Y if less than 10. 

The operand to AS, var, specifies the new i.v. For the 
remainder of the i.s., or until another AS is encountered, 
all operators refer to the new i.v. For example 
(FOR I FROM I TO Nl AS J FROM 1 TO N2 BY 2 

AS K FROM N3 TO 1 BY -1—-) terminates when I exceeds Nl, or 
J exceeds N2, or K becomes less than 1. After each 
iteration, I is incremented by 1, J by 2, and K by - 1 . 

Miscellaneous 

1. Lowercase versions of all i.s. operators are equivalent to the uppercase, 
e.g. , (for X in Y ...').. 

2. Each i.s. operator is of lower precedence than all INTERLISP forms, so 
parentheses around the operands can be omitted, and will be supplied where 
necessary, e.g., BIND (X Y 2) can be written BIND X Y Z, OLD (X«-form) as 
OLD X-form, WHEN (NUMBERP X) as WHEN NUMBERP X, etc. 
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3* RETURN or GO may be used in any operand. (In this case, the translation of 
the iterative statement will always be in the form of a PROG, nover a 
mapping function.) RETURN means return from the i.s. (with the indicated 
value), not from the function in which the i.s appears. GO refers to a 
label elsewhere in the function in which the i.s. appears, except for the 
labels $SLP,SSITERATE, and SSOUT which are reserved, as described in G 
below. 

4. In the case of FIRST, FINALLY, EACHTIHE, or one of the i.s. types, e.g. DO. 
COLLECT, SUM, etc., the operand can consist of more than one form, e.g., 
COLLECT (PRINT X:l) X:2, in which case a PROGN is supplied. 

5. Each operand can be the name of a function, in which case it is applied to 
the (last) i.v.,-* 49 60 e.g., FOR X IN Y DO PRINT WHEN NUMBERP, is the 
same as FOR X IN Y DO (PRINT X) WHEN (NUMBERP X). Mote that the i.v. need 
not be explicitly specified, e.g., IN Y DO PRINT WHEN NUMBERP will work. 

6. While the exact form of the translation of an iterative statement depends 
on which operators are present, a PROG will always be used whenever the 
i.s. specifies dummy variables, i.e. if a BIND operator appears, or there 
is more than one variable specified by a FOR operator, or a GO, RETURN, or 
a reference to the variable SSVAL appears in any of the operands. When a 
PROG is used, the form of the translation is: 



48 



49 



50 



For i.s. types, e.g. DO, COLLECT, JOIN, the function is always applied to 
the first i.v. in the i.s., whether explicity named or not. For example, 
(IN Y AS I FROM 1 TO 10 DO PRINT) prints elements on Y, not integers 
between 1 and 10. 

Mote that this feature does not make much sense for FOR, OLD, BIND, IN, or 
ON, since they "operate" before the loop starts, when the i.v. may not even 
be bound. 

In the case of BY in conjunction with IN, the function is applied to the 
current tail e.g., FOR X IN Y BY CDDR is the same as FOR X IN Y BY 

(CDDR X)... See page 23.24. 
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(PROG variables 

{initialize} 
SSLP {eachtime } 

{test} 

{body} 
SSI TERATE 

{aftertest} 

{update} 

(GO SSLP) 
SSOUT {finalize) 

(RETURN! SSVAL)) 

where {test} corresponds to that portion of the loop that tests for 
termination and also for those iterations for which {body} is not going to 
be executed, (as indicated by a WHEN or UNLESS); {body} corresponds to the 
operand of the i.s.type, e.g. DO, COLLECT, etc.; {aftertest} corresponds to 
those tests for termination specified by REPEATWHILE or REPEATUNTIL; and 
{update} corresponds to that part that resets the tail, increments the 
counter, etc. in preparation for the next iteration. {initialize}, 
{finalize}, and {eachtime} correspond to the operands of FIRST, FINALLY, 
and EACHTIME, if any. 

Note that since {body} always appears at the top level of the PROG, the 
user can insert labels in {body}, and go to them from within {body} or from 
other i.s. operands, e.g. (FOR X IN Y FIRST (GO A) DO (FOO) A (FIE)). 6i The 
user can also go to SSLP, SSITERATE or SSOUT, or explicitly set SSVAL. 

Errors in Iterative Statements 

An error will be generated and an appropriate diagnostic printed if any of the 
following conditions hold: 



However, since {body} is dwimified as a list of forms, the label(s) should 
be added to the dummy variables for the iterative statement in order to 
prevent their being dwimified and possibly 'corrected 1 , e.g. 
(FOR X IN Y BIND A FIRST (GO A) DO (FOO) A (FIE)). 
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1. Operator with null operand, i.e. two adjacent operators, as in FOR X IN Y 

UN Til DO — 

2. Operand consisting of more than one form (except as operand to FIRST, 
FINALLY, or one of the i.s. types), e.g., FOR X IN Y (PRINT X) COLLECT 

3. IN , ON, FROM, TO, or BY appear twice in same i.s. 

4. Both IN and ON used on same i.v. 

5. FROM or TO used with IN or ON on same i.v. 

6. More than one i.s. type , e.g. a DO and a SUM. 

In 3, 4, or 5, an error is not generated if an intervening AS occurs. 
If an error occurs, the i.s. is left unchanged. 

If no DO, COLLECT, JOIN or any of the other i.s. types are specified, CLISP will 
first attempt to find an operand consisting of more than one form, e.g., 
FOR X IN Y (PRINT X) WHEN ATOM X, and in this case will insert a DO after the 
first form. • (In this case 9 condition 2 is not considered to be met, and an 
error is not generated.) If CLISP cannot find such an operand, and no WHILE or 
UNTIL appears in the i.s., a warning message is printed: NO 0O„ COLLECT, OR 
JOIN: followed by the i.s. 

Similarly, if no terminating condition is detected, i.e. no IN, ON, WHILE , 
UNTIL, TO, or a RETURN or GO, a warning message is printed: 
POSSIBLE NON-TERMINATING ITERATIVE STATEMENT: followed by the i.s. However, 
since the user may be planning to terminate the i.s. via an error, control»E, 
or a retf rom from a lower function, the i.s. is still translated. 

Defining New Iterative Statement Operators 

The i.s. type specifies what is to be done at each iteration, e.g. collecting 
values on a list, adding numbers, searching for a particular condition, etc. 
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Each i.s. can have one and only one i.s.type. The function i .s .typo provides a 
means of defining new i.s. types. 



i .s . type[name ; form; others] name is the name of the i.s.type. form is the form 

to be evaluated at each iteration. In form SSVAL 
can be used to reference the value being 
assembled, I.V. to reference the current value of 
the i.v., and BODY to reference the body of the 
statement, i.e. name 's operand. 

For example, for COLLECT, form would be (SETQ SSVAL (NC0NC1 SSVAL BODY)), for 
SUM: (SSVAL-SSVAL+BODY), 62 for NEVER : (IF BODY THEN SSVAL^NIL (GO SSOUT))), 63 
THERE IS : ( IF BODY THEN SSVAL-I.V. (GO SSOUT)). 

others specifies an optional list of additional 
i.s. operators and operands which will be tacked 
on to the end of the i.s. For example, others for 
SUH is (FIRST $SVAL*0). 

i.s.type is undoable. 



Examples: 

1) To define RCOLLECT, a version of COLLECT which uses cons instead of nconcl 

and then reverses the list of values: 

i.s. type[ RCOLLECT ; ($SVAL-( CONS BODY SSVAL)); 

(FINALLY (RETURN (DREVERSE SSVAL)))] 



52 



68 



SSVAL+BODY is used instead of (IPLUS SSVAL BODY), so that the choice of 
function used in the translation, i.e. iplus , fplus , or plus , will be 
determined by the declarations then in effect. 

(IF BODY THEN RETURN NIL) would prevent any operations specif led via a 
FINALLY from being executed. 
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2) To define .TCOLLECT, a version of COLLECT which uses tconc : 



i.s.type[TCOLLECT;(TCOMC SSVAL BODY); 

(FIRST SSVALo(CONS) FINALLY (RETURN (CAR SSVAL)))] 

3) To define PRODUCT: i . s . type[ PRODUCT ; (SSVAL*S3VAL*B0DY );( FIRST SSVAL-1] 

i . s .type performs the appropriate modifications to the property list for name , 
as well as for the lower case version of name, and also updates the appropriate 
spelling lists. 

i . s . type can also be used to define synonyms for all i.s. operators, (not just 
those that are i.s. types), by calling i .s.type with form an atom, e.g. 
i.s. type[ WHERE ;WHEN ] makes WHERE be the same as WHEN. Similarly, following 
i.s, type[ ISTHERE ; THERE IS] one can write ( ISTHERE ATOM IN Y), and following 
i.s.type[FIND;FOR] and i.s. type[ SUCHTHAT ; THERE IS], one can write 
(FIND X IN Y SUCHTHAT X MEMBER I). 64 

This completes the description of iterative statements. 
23.8 CLISP Translations 

The translation of infix operators and IF | THEN I ELSE statements are handled in 
CLISP by replacing the CLISP expression with the corresponding INTERLISP 
expression, and discarding the original CLISP, because (1) the CLISP expression 



In the current system, WHERE is synonymous with WHEN, SUCHTHAT and ISTHERE 
with THEREIS, and FIND with FOR. 
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is easily recomputable (by clispify) , and (2) the INTERLISP expressions aro 
simple and straightforward. In addition to saving the space required to retain 
both the CLISP and the INTERLISP, another reason for discarding the original 
CLISP is that it may contain errors that were corrected in the course of 
translation, e.g. the user writes F00«-F000:1, N*8F00 X), etc. If the original 
CLISP were retained, either the user would have to go back and fix these errors 
by hand, thereby negating the advantage of having DWIM perform those 
corrections, or else DWIM would have to keep correcting these, errors over and 
over . 

Where (1) or (2) are not the case, e.g. with iterative statements, pattern 
matches, record expressions, etc. the original CLISP is retained (or a 
slightly modified version thereof), and the translation is stored elsewhere, 
usually in clisparray , a hash array. 57 6S The interpreter automatically checks 
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Note that clispify is sufficiently fast that it is practical for the user 
to configure his INTERLISP system so that all expressions are automatically 
clispify ed immediately before they are presented to him. For example, he 
can define an edit macro to use in place of P which calls clispify on the 
current expression before printing it. Similarly, he can inform prettyprint 
to call clispify on each expression before printing it, etc. 

The handling of translations for IF | THEN | ELSE statements is determined by 
the value of clispif tranf lg . If T, the translations are stored elsewhere, 
and the (modified) CLISP retained as described below, if NIL, the 
corresponding COND replaces the IF I THEN I ELSE expression. The initial value 
of clispiftranf lg is NIL. 

The actual storing of the translation is performed by the function 
clisptran , page 23.76, 

The user can also indicate that he wants the original clisp retained by 
embedding it in an expression of the form (CLISP . cl 1sp-express1on ) , e.g. 
(CLISP X: 5:3) or (CLISP <A B C ! D>). In such cases, the translation will 
be stored remotely as described in the text. Furthermore, such expressions 
will be treated as clisp even if infix and prefix transformations have been 
disabled by setting clispf lg to NIL, as described on page 23.75. In other 
words, the user can instruct the system to interpret as clisp infix or 
prefix constructs only those expressions that are specif ically flagged as 
such . 
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50 

this array using gethash when given a form car of which is not a function. v 
Similarly, the compiler performs a gethash when given a form it does not 
recognize to see if it has a translation, which is then compiled instead of tho 
form. Whenever the user changes a CL1SP expresson by editing it, the editor 
automatically deletes its translation (if one exists), so that the next time it 
is evaluated or dwimified, the expression will be retranslated The function 
ppt and the edit commands PPT and CLISP: are available for examining 
translations, see page 23.80. Similarly, if prettytranf lg is T, prottyprint 
will print the translations instead of the corresponding CLISP expression , 6i 



If clisparray is NIL, 62 translations are implemented instead by replacing the 
CLISP expression by an expression of the form 

(CLISP%_ translation . CLISP-expression ) , 63 e.g. (FOR X IN Y COLLECT (CAR X)) 
would be replaced by 
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62 



63 



CLISP translations can also be used to supply an interpretation for funtion 
objects, as well as forms, either for function objects that are used 
openly, i.e. appearing as car of form, function objects that are explicitly 
apply ed, as with arguments to mapping functions, or function objects 
contained in function definition cells. In all cases, if car of the object 
is not LAMBDA or NLAMBDA, the interpreter and compiler will check 
clisparray . 

If the value of clispretranf lg is T, dwimlfy will also ( retranslate any 
expressions which have translations stored remotely. The initial value of 
clispretranf lg is NIL, 

Note that the user can always examine the translation himself by performing 
(GETHASH expression CLISPARRAY). 

clisparray is initially NIL, and ^clisparray is its size. The first time a 
translation is performed, a hash array of this size is created. Therefore 
to disable clisparray , both it and #clisparray should be set to NIL. 

CLISP%_ is an atom consisting of the six characters C, L, I, S, P, and 
space, which must be preceded by the escape character % in order for it to 
be included as a part of an identifier. The intent was to deliberately 
make this atom hard to type so as to 1 make it unlikely that it would 
otherwise appear in a user's program or data, since the editor and 
prettyprint treat it very specially, as described above. 
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(■CLISP%_ (MAPCAR Y (FUNCTION CAR) ) FOR X IN Y COLLECT (CAR X)). Both tho 

editor and prettyprint know about CLISP e /._ expressions and treat them specially 
by suppressing the translations: Prettyprint prints just the CUSP 
(unless prettytranf lg «T, as described below), while the editor makes the 
translation completely invisible, e.g. if the current expression were the above 
CLISP%_ expression, F MAPCAR would fail to find the MAPCAR, and (3 ON) would 
replace IN with ON, i.e. the editor operates as though both the CLISP%_ and tho 
MAPCAR were not there. As with translations implemented via clisparray, if the 
CLISP expression is changed by editing it, the translation is automatically 
deleted. 

CLISP%_ expressions will interpret and compile correctly: CLISP%_ is defined as 
an nlambda nospread function with an appropriate compiler macro. Note that if 
the user sets clisparray to NIL, he can then break, trace, or advise CLISP%_ to 
monitor the evaluation of iterative statements, pattern matches, and record 
operations. This technique will work even if clisparray was not NIL at the time 
the expressions were originally translated, since setting clisparray to NIL 
will effectively delete the translations, thereby causing the CLISP expressions 
to be retranslated when they are first encountered. Note that if the user only 
wishes to monitor the CLISP in a certain function, he can accomplish this by 
embedding its definition in (RESETVAR CLISPARRAY NIL *). 

If a CLISP%_ expression is encountered and clisparray is not NIL, the 
translation is transferred to the hash array, and the CLISP°X_ expression 
replaced by just the CLISP. Setting prettytranf lg to CLISP%_ causes 
prettyprint to print CLISP expressions that have been translated in the form of 
(CLISP%_ translation . CLISP-expresslon), even if the translation is currently 
stored in clisparray . These two features together provide the user with a way 
of dumping CLISP expressions together with their translations so that when 
reloaded (and run or dwimified), the translations will automatically be 
transferred to clisparray . 
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In summary, if prettytranf lg sNIL, only the CLISP is printed (used for producing 
listings). If prettytranf lg =T , only the translation is printed (used for 
exporting programs to systems that do not provide CLISP, and to examine 
translations for debugging purposes).^ If prettytranf lg =C LIS ?% , an expression 
of the form (CLI5P%_ translation . CLISP) is printed, (used for dumping both 
CLISP and translations). The preferred method of storing translations is in 
clisparray , so that if any €LXSP%_ expressions are converted while clisparray 
is not NIL, they will automatically be converted so as to use clisparray . If 
clisparray =NIL, they will be left alone, and furthermore, new translations will 
be implemented using CLISP%_ expressions. 

23.9 Declarations 

Declarations are used to affect the choice of INTERLISP function used as tho 
translation of a particular operator. For example, A*B can be translated as 
either (IPLUS A B), (FPLUS A 8), or (PLUS A 8), depending on the declaration in 
effect. Similarly X:KY can mean (RPLACA X Y), (FRPLACA X Y), or 
( VRPLACA X Y), and <NA B> either (NC0NC1 A B) or (/NC0NC1 A B). The table 
below gives the declarations available in CLISP, and the INTERLISP functions 
they indicate. The choice of Junction on all CLISP transformations are 
affected by these declarations, i.e. iterative statements, pattern matches, 
record operations . as well as infix and prefix operators. 

The user can make (change) a global declaration by calling the function 
CLISPDEC and giving it as its argument a list of declarations, e.g., 
(CLISPDEC (QUOTE (FLOATING UNDOABLE) ) ) . Changing a global declaration does not 
affect the speed of subsequent CLISP transformations, since all CLISP 



Note that makefile will reset prettytranf Ig to T, using resetvar , when 
called with the option NOCLISP. 
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transformation are table driven (i.e. property list), and global declarations 
are accomplished by making the appropriate internal changes to CUSP at tho 
time of the declaration. If a function employs local declarations (doscribod 
below), there will be a slight loss in efficiency owing to the fact that for 
each CUSP transformation, the declaration list must be searched for possibly 
relevant declarations. 

Declarations are implemented in the order that they are given, so that later 
declarations override earlier ones. For example, the declaration FAST 
specifies that FRPLACA, FRPLACD, FMEMB, and FLAST be used in place of RPLACA, 
RPLACO, MEMB , and LAST; the declaration RPLACA specifies that RPLACA be used. 
Therefore, the declarations (FAST RPLACA RPLACD) will cause FMEMB , FLAST, 
RPLACA, and RPLACD to be used. 



The initial global declaration is INTEGER and STANDARD. 



Table of Declarations 



Declaration 



INTERLISP functions to be used 



INTEGER or FIXED 

FLOATING 

MIXED 

FAST 

UNDOABLE 
STANDARD 



RPLACA, RPLACD, 
/RPLACA, ... 



IPLUS, IMINUS, IDIFFERENCE, ITIMES. IQUOTIENT, ILESSP, 
IGREATERP 

FPLUS, FMINUS, FDIFFERENCE, FTIMES, FQUOTIENT, LESSP, 
FGTP 

PLUS, MINUS, DIFFERENCE, TIMES, QUOTIENT, LESSP, 
GREATERP 

FRPLACA, FRPLACD, FMEMB, FLAST, FASSOC 

/RPLACA, /RPLACD, /NCONC, /NC0NC1, /MAPCONC, /MAPCON 

RPLACA, RPLACD, MEMB, LAST, ASSOC, NCONC, NCONC 1, 
MAPCONC, MAPCON 

corresponding function 
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Local Declarations 



The user can also make declarations affecting a selected function or functions 
by inserting an expression of the form (CUSP: . declarations) immodiatoly 
following the argument list, i.e., as CADDR of the definition. Such local 
declarations take precedence over global declarations. Declarations affecting 
selected variables can be indicated by lists, where the first element is the 
name of a variable, and the rest of the list the declarations for that 
variable. For example, (CUSP : FLOATING (X INTEGER) ) specifies that in this 
function integer arithmetic be used for computations involving X, and floating 
arithmetic for all other computations. The user can also make local record 
declarations by inserting a record declaration, e.g. (RECORD --), 
(ARRAYRECORD --), etc., in the local declaration list. Local record 
declarations override global record declarations for the function in which they 
appear. Local declarations can also be used to override the global setting of 
certain DWIM/CL1SP parameters effective only for transformations within that 
function, by including in the local declaration an expression of the form 
(variable = value), e.g. (PATVARDEFAULT = QUOTE) . 

The CLISP: expression is converted to a comment of a special form recognized by 
CLISP . Whenever a CLISP transformation that is affected by declarations is 
about to be performed in a function, this comment will be searched for a 
relevant declaration, and if one is found, the corresponding function will be 
used. Otherwise, if none are found, the global declaration(s) currently in 
effect will be used. 



'involving 1 means where the variable itself is an operand. For example, 
with the declaration (FLOATING (X INTEGER) ) in effect, (FOO X)+(FIE X) 
would translate to FPLUS, i.e., use floating arithmetic, even though X 
appears somewhere inside of the operands, whereas X+(FIE X) would translate 
to IPLUS . If there are declarations involving both operands, e.g. X+Y, 
with (X FLOATING) (Y INTEGER), whichever appears first in the declaration 
list will be used. 
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Local declarations are effective in the order that they are given, so that 
later declarations can be used to override earlier ones, e.g. 
(CLIS'P: FAST RPLACA RPLACD) specifies that FMEMB, FLAST, RPLACA, and RPLACD bo 
used. An exception to this is that declarations for specific variables take 
precedence of general, function-wide declarations, regardless of the order of 
appearance, as in (CUSP: (X INTEGER) FLOATING) . 

Clispify also checks the declarations in effect before selecting an infix 
operator to ensure that the corresponding CUSP construct would in fact 
translate back to this form. For example, if a FLOATING declaration is in 
effect, clispify will convert (FPLUS X Y) to X+Y, but leave ( IPLUS X Y) as is. 
Mote that if (FPLUS X Y) is CLISPIFYed while a FLOATING declaration is under 
effect, and then the declaration is changed to INTEGER, when X4-Y is translated 
back to INTER-LISP, it will become (IPLUS X Y), 



23.10 The Pattern Match Compiler *" 7 

CLISP contains a fairly general pattern match facility. The purpose of this 
pattern match facility is to make more convenient the specifying of certain 
tests that would otherwise be clumsy to write (and not as intelligible), by 
allowing the user to give instead a pattern which the datum is supposed to 
match. Essentially, the user writes "Does the (expression) X look like 
(the pattern) P?" For example, X: (& *A ~ *B) asks whether the second element 
of X is an A, and the last element a B. The implementation of the matching is 
performed by computing (once) the equivalent INTERLISP expression which will 
perform the indicated operation, and substituting this for the pattern, and not 
by invoking each time a general purpose capability such as that found in FLIP 



fifl 

The pattern match compiler was written by L. M. Masinter. 
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or PLANNER. For example, the translation of X:(& 'A 'B) is: 
(AND (EO ( CADR X) (QUOTE A)) (EQ (CAR (LAST X)) (QUOTE B))). Thus the CL1SP 
pattern match facility is really a Pattern Compiler, and the emphasis in its 
design and implementation has been more on the efficiency of object code than 
on generality and sophistication of its matching capabilities. The goal was to 
provide a facility that could and would be used even where efficiency was 
paramount, e.g. in inner loops. As a result, the CL1SP pattern pnitch facility 
does not contain (yet) some of the more esoteric features of other pattern 
match languages, such as repeated patterns, disjunctive and conjunctive 
patterns, recursion, etc. However, the user can be confident that what 
facilities it does provide will result in INTERLISP expressions comparable to 

87 

those he would generate by hand. 

The syntax for pattern match expressions is form:pattern 9 where pattern is a 
list as described below. As with iterative statements, the translation of 
patterns, i.e., the corresponding INTERLISP expressions, are stored in 
clisparray , a hash array, as described on page 23.31. The original expression, 
form.-pattern, is replaced by an expression of the form 
(MATCH form WITH pattern). CLISP also recognises expressions input in this 
form. 

If form appears more than once in the translation, and it is not either a 
variable, or an expression that is easy to (re)compute, such as (CAR Y), 
tcDDR Z), etc., a dummy variable will be generated and bound to the value of 
form so that form is not evaluated a multiple number of times. For example, 
the translation of (F00 X):(S «A $) is simply (MEMB (QUOTE A) (FOO X)), while 
the translation of (FOO X):('A 'B --) is: 



Wherever possible, already existing INTERLISP functions are used in the 
translation, e.g., the translation of (S *A S) uses MEMB, ($ (*A S) S) uses 
ASSOC, etc. 
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[PROG (SS2) (RETURN 

(AND (EO (CAR (SETO SS2 (FOO X))) 
(QUOTE A)) 
(EO (CAOR S$2) (QUOTE BJ. 

In the interests of efficiency, the pattern match compiler assumes that all 
lists end in NIL, i.e. there are no LISTP checks inserted in the translation to 
check tails. For example, the translation of X:(*A & ) is 
(AND (EQ (CAR X) (QUOTE A)) (CDR X)) f which will match with (A B) as well as 
(A . B). Similarly, the pattern match compiler does not insert LISTP checks on 
elements, e.g. X:(('A «-) translates simply as (EQ (CAAR X) (QUOTE A)), and 
X:((51 51 --) as (CDAR X) . 68 Note that the user can explicitly insert LISTP 
checks himself by using .6, as described on page 23.42, e t g. 
X:((S1 $1 --)@LISTP --) translates as (CDR (LISTP (CAR X))). 



Pattern Elements 



A pattern consists of a list of pattern elements. Each pattern element is said 
to match either an element of a data structure or a segment, (cf . the editor's 
pattern matcher, matches any arbitrary segment of a list, while & or a 

subpattern match only one element of a list.) Those patterns which may match a 
segment of a list are called SEGMENT patterns; those that match a single 
element are called ELEMENT patterns. 



The insertion of LISTP checks for elements is controlled by the variable 
patlistpcheck . When patlistpcheck is T, LISTP checks are inserted, e.g. 
X:(('A --) translates as: 

(EQ (CAR (LISTP (CAR (LISTP X)))) (QUOTE A)) 
patlistpcheck is initially NIL. Its value can be changed within a 
particular function by using a local declaration, as described on page 
23.37. 
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Element Patterns 



There are several types of element patterns, best given by their syntax: 



PATTERN 



MEANING 



Si, or & 



matches an arbitrary element of a list 



* expression 



matches only an element which is equal to the given 
expression e.g., % A 9 69 • (A B) . 



= form 



matches only an element which is equal to the value of form, 
e.g., =X, REVERSE Y). 



--form 



same as s, but uses an eg check instead of equal , 



atom treatment depends on setting of patvardefault . 

If Patvardefault is 1 or QUOTE, same as 'atom. 
If patvardefault is s or EQUAL, same as satom. 
If patvardefault is ss or EQ, same as ssatom. 
If patvardefault is *■ or SETQ, same as atom«-&. 

70 

patvardefault is initially *. 

Mote: numbers and strings are always interpreted as though patvardefault were 
= , regardless of its setting. Eg, memb , and assoc are used for comparisons 
involving small integers. 



69 



70 



eg , memb , and assoc are automatically used in the translation when the 
quoted expression is atomic, otherwise equal , member , and sassoc . 

patvardefault can be changed within a particular function by using a local 
declaration, as described on page 23.37. 
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( pattern^ ... pattern n ) n > 1 matches a list which matches the given 

patterns, e.g., (& &), ( 'A). 

e 1 emen t - pa ttern(? function -object matches an element if the element-pattern 

matches it, and the function-object (name of a function or a 
LAMBDA expression) applied to that element returns non-NIL, 
e.g. &$NUMBERP matches a number, ('A )@F00 matches a list 
whose first element is A, 8 and for which F00 applied to that 
list is non-NIL/ 1 



* matches any arbitrary element. If the entire match 

succeeds, the element which matched the 561 will be returned 
as the value of the match. 

Mote: normally, the pattern match compiler constructs an expression whose value 
is guaranteed to be non-NIL if the match succeeds and NIL if it fails. 
However, if a * appears in the pattern, the expression generated will either 
return NIL if the match fails, or whatever matched the * even though that may 
be NIL, For example, X:('A * ) translates as 

(AND (EQ (CAR X) (QUOTE A)) (CADR X)). 



-element-pattern matches an element if the element is wot matched by 

element-pattern, e.g. -'A, -=X, <*.(-- 'A --). 



For 'simple 1 tests, the function-object is applied before a match is 
attempted with the pattern, e.g. ((-- 'A -~)@LISTP translates as 

(AND (LISTP (CAR X)) (MEMB (QUOTE A) (CAR X))), not the other way around. 
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Segment Patterns 



S, or matches any segment of a list (including one of zero 

length) . 

The difference between $ and is in the type of search they generate. For 
example, X:(S 'A 'B 5) translates as (EQ (CADR (MEMB (QUOTE A) X) ) (QUOTE B ) ) , 
whereas X:(-- 'A 'B S) translates as: [SOME X (FUNCTION ( LAMBDA (SS2 SSI) 
(AND (EQ SS2 (QUOTE A)) (EQ (CADR $$1) (QUOTE B]. Thus, a paraphrase of 
(S • A 'B S) would be "Is the element following the first A a B?", whereas a 
paraphrase of (-- 'A 'B S) would be "Is there any A Immediately followed by a 
B?" Note that the pattern employing & will result in a more efficient search 
than that employing However, (S 'A 9 B S) will not match with 

(XYZAMNOABC), but (-- • A 'B S) will. 

Essentially, once a pattern following a S matches, the $ never resumes 
searching, whereas produces a translation that will always continue 

searching until there is no possibility of success. However, if the pattern 
match compiler can deduce from the pattern that continuing a search after a 
particular failure cannot possibly succeed, then the translations for both 
and S will be the same. For example, both X:(S *A $3 $) and (-- 'A S3 «- ) 
translate as (CDDDR (MEMB (QUOTE A) X)), because if there are not three 
elements following the first A, there certainly will not be three elements 
following subsequent A's, so there is no reason to continue searching, evon for 
Similarly, (S 'A $ 'B $) and (-- 'A ! B are equivalent. 

$2, S3, etc. matches a segment of the given length. Note that $1 is not 

a segment pattern. 

! element-pattern matches any segment which the given element pattern would 

match as a list. For example, if the value of FOO is 
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(A B C) !=F00 will match the segment ...ABC ... etc. 
Note that ! * is permissible and means Value-of -matches, e.g. 
X:($ 'A !*) translates to (COR (MEMB (QUOTE A) X)). 

Mote: since ! appearing in front of the last pattern specifies a match with 
some tail of the given expression, it also makes sense in this case for a I to 
appear in front of a pattern that can only match with an atom, e.g., ($2 ! *A) 
means match if cddr of the expression is the atom A. Similarly, X: (S ! *A) 
translates to (EQ (CDR (LAST X)) (QUOTE A)). 

fatom treatment depends on setting of patvardef ault . If 

patvardefault is 1 or QUOTE, same as ! 'atom (see above 
discussion). If patvardefault is = or EQUAL, same as 
Jsatom. If patvardefault is ss or EQ, same as !^=atom. If 
patvardefault is * or SETQ, same as atom*-$. 

The atom •.' is treated exactly like ! /■ In addition, if a 
pattern ends in an atom, the 1 . 1 is first changed to ! . 
e.g., ($1 .A) and ($1 ! A) are equivalent, even though the 
atom'-'.. 1 does not explicitly appear in the pattern. 

Segment-pattern@function-object matches a segment if the segment-pattern 

matches it, and the function object applied to the 
corresponding segment (as a list) returns non-NIL, e.g. 



With one exception, namely • , ' preceding an assignment does not have the 
special interpretation that ! has preceding an assignment (see page 
23.45). For example, X : ( 1 A . FOO- 1 B ) translates as: 

(AND (EQ (CAR X) (QUOTE A)) (EQ (CDR X) (QUOTE B)) (SETQ FOO (CDR X))), 
but X:('A ! FOQ-'B) translates as: 

(AND (EQ (CAR X) (QUOTE A)) 

(NULL (CDDR X)) 

(EQ ( CADR X) (QUOTE B)) 

(SETQ FOO (CDR X))). 
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(S@CDDR 'D S) matches (A B C D E) but not (A B D E), since 
CDDR of (A B) is NIL. 

Mote: an @ pattern applied to a segment will require computing tho 
corresponding structure (with Idif f ) each time the predicate is applied (except 
when the segment in question is a tail of the list being matched). 



Assignments 

Any pattern element may be preceded by a variable and a * + meaning if the 
match succeeds (i.e., everything matches), the variable given is to be set to 
what matches that pattern element. For example, if X . « (A BCD E), 
X:($2 Y*-53) will set Y to (C D E). Assignments are not performed until the 
entire match has succeeded. Thus, assignments cannot be used to specify a 
search for an element found earlier in the match, e.g. X:(Y«-$1 =Y --) u will 
not match with ( A A B C . . . ) This type of maitch is achieved by using 
place-markers, described below. 

If the variable is preceded by a ! , the assignment is to the tail of the list 
as of that point in the pattern, i.e. that portion of the list matched by the 
remainder of the pattern. For example, if X is (ABC D E), X:(S lY^C 1 D S) 
sets Y to (C D E), i.e. eddr of X. In other words, when ! precedes an 
assignment, it acts as a modifier to the and has no effect whatsoever on the 
pattern itself, e.g. X:('A *B) and X:('A IFOO'B) match identically, and in 
the latter case, F00 will be set to CDR of X. 



The translation of this pattern is: 
(COND ( (AND (CDR X) (EQUAL (CADR X) Y)) 

(SETQ Y (CAR X)) 

T)). 

The AND is because if Y is NIL, the pattern should match with (A NIL), but 
not with just (A). The T is because (CAR X) might be NIL, 

unless, of course, the value of Y was A before the match started. 
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Mote: ^^-pattern-element and ! **-pattern-element are acceptable, e.g. 

X: ($ »A «*-( »B --) translates as: 

[PROG (SS2) (RETURN 

(AND (EQ (CAADR (SETQ $S2 (MEMB (QUOTE A) X))) 
(QUOTE B) ) 
(CADR SS2] 



Place-markers 



Variables of the form #n, n a number,, are called place-markers, and are 
interpreted specially by the pattern match compiler. Place-markers are used in 
a pattern to mark or refer to a particular pattern element. Functionally, they 
are used like ordinary variables, i.e. they can be assigned values, or used 
freely in forms appearing in the pattern, e.g. X: »(ADD1 #1 ) ) will match 

the list (2 3). However, they are not really variables in the sense that they 
are not bound, nor can a function called from within the pattern expect to be 
able to obtain their values. For convenience, regardless of the setting of 
patvardef ault , the first appearance of a defaulted place-marker is interpreted 
as though patvardefault were Thus the above pattern could have been written 
as X:(#l =(ADD1 #1)). Subsequent appearances of a place-marker are interpreted 
as though patvardefault were = . For example, X:(#l #1 --) is equivalent to 
X:(#1-S1 =#1 — ), and translates as (AND (CDR X) (EQUAL (CAR X) (CADR X))/ 6 

Replacements 

Any pattern element may be followed by a ' and a form, meaning if the match 

succeeds, the part of the data that matched is to be replaced (e.g., with 

RPLACA or RPLACD) 76 with the value of <form>. For example, if X «(A B C D E), 



Just (EQUAL (CAR X) (CADR X)) would incorrectly match with (NIL). 

The user can indicate he wants /rplaca and /rplacd used, or f rplaca and 
f rplacd , by means of declarations. The initial default is for rplaca and 
rplacd . 
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X:(S 'C S1«~Y SI) will replace the fourth element of X with the value of Y. As 
with assignments, replacements are not performed until after it is determined 
that the entire match will be successful . 

Replacements involving segments splice the corresponding structure into the 

list being matched, e.g. if X is (A B C 0 E F) and F00 is (1 2 3), after the 

pattern ('A S«-FOO 'D S) is matched with X, X will be (A 1 2 3 D E F), and FOO 
will be eg to CDR of x, i.e. (1 2 3 D E F). 

* a a 

Note that (S FOOFIE $) is ambiguous, since it is not clear whether FOO or FIE 
is the pattern element, i.e. whether *• specifies assignment or replacement. 
For example, if patvardef ault is =, this pattern can be interpreted as 
(5 FOO«-=FIE $), meaning search for the value of FIE, and if found set FOO to 
it, or (S =FOO«-FXE $) meaning search for the value of FOO, and if found, store 
the value of FIE into the corresponding position. In such cases, the user 
should disambiguate by not using the patvardefault option, i.e. by specifying ' 
or = . 

Reconstruction 

The user can specify a value for a pattern match operation other than what is 

returned by the match by writing after the pattern 2> followed by another form, 

e.g. X:(FOO-$ 'A --) => (REVERSE FOO)/ 7 which translates as: 

[PROG (S$2) (RETURN 

(COND ((SETO S$2 (MEMB (QUOTE A) X)) 
(SETQ FOO (LDIFF X S2)) 
(REVERSE FOO]. 



The original CLISP is replaced by an expression of the form 
(MATCH forml WITH pattern => form2) . CLISP also recognizes expressions 
input in this form. 
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Place-markers in the pattern can be referred to from within form , e.g. tho 
above could also have been written as X:( !#1 'A -«>>(REVERSE ft). If -> is 
used in place of the expression being matched is also physically changed to 
the value of form . For example, X:(#l 1 A !#2) -> (CONS #1 #2) would remove tho 
second element from X, if it were equal to A. 

In general, f orml :pattern->form2 is translated so as to compute form2 if the 
match is successful, and then smash its value into the first node of f orml . 
However, whenever possible, the translation does not actually require form2 to 
be computed in its entirety, but instead the pattern match compiler uses f orm2 
as an indication of what should be done to forml . For example, 
X:(#l 'A !#2) -> (CONS #1 #2) translates as: 
(AND (EQ (CADR X) (QUOTE A)) (RPLACD X (CDDR X))). 

Examples 

X :( 'A matches any arbitrary segment. 'A matches only an 

A, and the 2nd again matches an arbitrary segment; 
thus this translates to (MEMB (QUOTE A) X). 

X-:('-- 'A) Again, matches an arbitrary segment; however, since 

there is no after the 'A, A must be the last element 
of X, Thus this translates to: 

(EQ (CAR (LAST X)) (QUOTE A)). 

X:('A *B — *C $3 --) CAR of X must be A, and CADR must be B, and there must 

be at least three elements after the first C, so the 

translation is: 

(AND (EQ (CAR X) (QUOTE A)) 
(EQ (CADR X) (QUOTE B)) 
(CDDDR (MEMB (QUOTE C J (CDDR X)))) 



23.48 



X:(('A 'B) 'C Y*-S1 S) Since ('A 'B) does not end in S or --, (CODAR X) must 

be NIL. 
(COND 

( (AND (EO (CAAR X) (QUOTE A)) 
(EO (CADAR X) (QUOTE B)) 
(NULL (CDDAR X)) 
(EQ (CADR X) (QUOTE C)) 
(CDDR X)) 
(SETQ Y (CADDR X)) 
T)) 



X:(#l 'A $ 1 B 'C #1 $) #1 is implicitly assigned to the first element in the 

list. The 5 searches for the first B following A. This 

B must be followed by a C, and the C by an expression 

equal to the first element. 

[PROG (SS2) (RETURN 

(ANO (EQ (CADR X) (QUOTE A)) 

(EQ [CADR (SETQ SS2 (MEMB (QUOTE B) (CDDR X] 
(QUOTE C)) 

(CDDR $$2) * 
(EQUAL (CADDR SS2) (CAR X] 



X:(#l *A -- 'B 'C #1 S) Similar to the pattern above, except that specifies 

a search for any B followed by a C followed by the 

first element, so the translation is: 

[AND (EQ (CADR X) (QUOTE A)) 

(SOME (CDOR X) (FUNCTION (LAMBDA (532 $$1) 
(AND (EQ S$2 (QUOTE B) ) 

(EQ (CADR SSI) (QUOTE C)) 
(CDDR SSI) 

(EQUAL (CADDR $$1) (CAR X] 



This concludes the description of the pattern match compiler. 
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23.11 The Record Package 



The advantages of "data-less" or data-structure-independent programming have 
long been known: more readable code, fewer bugs, the ability to change the data 
structure without having to make major modifications to the program, etc. The 
record package in CL1SP both encourages and facilitates this good programming 
practice by providing a uniform syntax for accessing and storing data into many 
different types of data structures, e.g. those employing arrays, list 
structures, atom property lists, hash links, etc;, or any combination thereof, 
as well as removing from the user the task of writing the various access and 
storage routines themselves. The user declares (once) the data structure(s) 
used by his programs, and thereafter indicates the manipulations of the data in 
a data-structure-independent manner. The record package automatically computes 
from the declaration(s) the corresponding 1WTERLISP expressions necessary to 
accomplish the indicated access/storage operations. The user can change his 
data structure simply by changing the corresponding declaration(s) , and his 
program automatically (re)adjusts itself to the new conventions. 

The user informs the record package about the format of his data structure by 
making a record declaration. A record declaration defines a record , i.e. a 
data structure. (Note that the record itself is an abstraction that exists 
only in the user's head.) The record declaration is essentially a template 
which describes the record, associating names with its various parts or fields. 
For example, the record declaration (RECORD MSG (ID (FROM TO) . TEXT)) 
describes a data structure called MSG, which contains four fields: ID, FROM , 
TO, and TEXT. The user can then reference these fields by name, either to 
retrieve their contents, or to store new data into them, by using the : 
operator followed by the field name. For example, for the above record 



The record package was written by L« M. Masinter. 
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declaration, X:FROM would be equivalent (and translate) to (CAADR X), and 
Y:TO-Z to (RPLACA (CDADR Y) l)7 9 The fields of a record can be further broken 
down into subfields by additional declarations within the record, e.g. 

(RECORD MSG (ID (FROM TO) . TEXT) (RECORD TEXT (HEADER TXT))) 
would permit the user to refer to TEXT, or to its subfields HEADER and TXT. 

Note that what the record declaration is really doing is specifying tho 
data- paths of the structure, and thereby specifying how the corresponding 
access/storage operations are to be carried out. For example, 
(RECORD MSG (ID (FROM TO) . TEXT) (RECORD TEXT (HEADER TXT))) says the HEADER 
of a MSG is to be found as the first element of its TEXT, which is the second 
tail of the MSG itself. Hence, X:HEADER«-str ing is achieved by performing 
(RPLACA (CDDR X) string). 

Note also that when the user writes XiHEADER, he is implicitly saying the X is 
an instance of the record MSG, or at least is to be treated as such for this 
particular operation . In other words, the interpretation of X:FORM never 
depends on the value of X. The record package (currently) does not provide any 
facility which uses run-time checks to determine data paths, nor is there any 
error checking other than that provided by 1NTERLISP itself. For example, if X 
happened to be an array, X: HEADER would still compute (CADDR X) . S0 

The user may also elaborate a field by declaring that field name in a separate 



or /RPLACA or F RPLACA, depending on the CLISP declaration in effect. Note 
that the value of X:TO*-Z is neither X, X:T0, nor Z. In general, the usor 
should not depend on the value of a replacement record operation as it may 
differ from one record type to the next. 



However, it is possible to make the interpretation of X: HEADER differ from 
that of Y:HEADER (regardless of the values of X and Y), by using local 
record declarations, as described on page 23,37. Note that this 
distinction depends on a .tran6iation~time check, not run-time. 
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record declaration (as opposed to an embedded declaration). For example, the 
two declarations 

(RECORD MSG (ID (FROM TO) . TEXT)) and (RECORD TEXT (HEADER . TXT)) 
subdivide TEXT into two subfields. The user may then specify X:MSG .HEADER to 
achieve the interpretation n X is a MSG, retrieve its HEADER" . 51 The central 
point of separate declarations is that the record is wot tied to another record 
(as with embedded declarations), and therefore can be used in many different 
contexts. For example, one might additionally have a declaration 
( RECORD REPLY (TEXT TO . RESPONSE) ) . In this case, one could specify 
X: REPLY. HEADER to mean that X is a REPLY, and to retrieve (CAARX). In 
general, the user may specify as a data path a chain of record/field names, 
e.g. X: MSG. TEXT. HEADER. SUBHEAD. . . etc., where there is some path from each 
record to the next in the chain. Only as much of the path as is necessary to 
disambiguate it needs to be specified. For example, with the above declarations 
of MSG, TEXT, and REPLY, the path X:MSG. HEADER is unambiguous (it must go thru 
TEXT); however, X:TEXT is not, as this could mean that X is either a MSG or a 
RESPONSE. 52 

RECORD (used to specify elements and tails of a list structure) is just one of 
several record-types currently implemented. For example, the user can specify 
•optional* fields, i.e. property list format, by using the record type 
PROPRECORD; or fields to be associated with parts of the data structure via 
hash links, by using the record-type HASHRECORD; or that an entirely new 
data-type be allocated with both pointer and unboxed number fields by using the 
record type DATATYPE; or even specify the access definitions in the record 



X : HEADER by itself is interpreted to mean that X is an instance of TEXT, 
and translates as (CAR X). 

In this case, the message AMBIGUOUS RECORD FIELD is printed and an error is 
generated. If a data-path rather than a single field is ambiguous, (e.g. if 
there were yet another declaration (RECORD TO (NAME . HEADER)) and the user 
specified X: MSG. HEADER), the error AMBIGUOUS DATA PATH is generated. 
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declaration himself, by using the record-type ACCESSFN. These are described in 
detail below. 

The record package also provides a facility for creating new data structures 
using a record declaration as a guide or template. Initial values for tho 
various fields can be specified in the CREATE expression, or defaulted to 
values specified in the record declaration itself. Alternatively, CREATE can 
be instructed to use an existing datum as a model, i.e. to obtain the field 
values for the new datum from the corresponding fields of the existing datum, 
or even to actually re-use the structure of the existing datum itself. 

Additionally, the record package provides the facility for testing a data 
structure to determine if it is an instance of a given record, via a TYPE? 
expression . 

As with all DWIN/CLISP facilities, the record package contains many 
do-what-I-mean features, spelling correction on field names, record types, etc. 
In addition, the record package includes a RECORDS prettydef macro for dumping 
record declarations, as well as the appropriate modifications to the file 
package (Section 14), so that f iles? and cleanup will inform the user about 
records that need to be dumped. 

Record Declarations 

A record declaration is an expression of the form 

(record-type record-name fields . {defaults and/or subfields}) 
This expression is evaluated to effect the corresponding declaration. 



Local record declarations are performed by including an expression of this 
form in the CL1SP declaration for that function (page 23.37), rather than 
evaluating the expression itself. 
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recor d-type' specifies the "type" of data being described by the record 
declaration, and thereby implicitly specifies the data paths, i.e. how the 
corresponding access/storage operations are performed, record-type 
currently is either RECORD, TYPERECORD, ARRAYRECORD, ATOMRECORD, PROPRECORD, 
HASHRECORD, DATATYPE, or ACCESSFN. RECORD and TYPERECORD are used to 
describe list structures, DATATYPE to describe user data-types, ARRAYRECORD 
to describe arrays, ATOMRECORD to describe (the property list of) atoms, and 
PROPRECORD to describe lists that use property list format. HASHRECORD can 
be used with any type of data: since it simply specifies the data path to be 
a hash-link. ACCESSFN is also type-less; the user specifies the 
data-path(s) in the record declaration itself, as described below. 

2 . record-name is a literal atom used to identify the record declaration for 
dumping to files via the RECORDS prettydef macro, and for creating instances 
of the record via CREATE. For most top-level declarations, record-name is 
optional, e.g. (RECORD (ID (FROH TO) . TEXT) ) is perfectly acceptable. 54 

For TYPERECORD, record-name is obligatory and is used as an indicator in CAR 

of the datum to signify what "type" of record it is. CREATE will insert an 

extra field containing record-name at the beginning of the structure, and 

the translation of the access and storage functions will take this extra 

ft 

field into account. 

For subfield declarations, record-name is also obligatory, and specifies the 
parent field that is being elaborated, as described below. 



If record-name is omitted, it simply means that the user cannot specify the 
record by name, e.g. in CREATE expressions, or when using the RECORDS 
prettydef command. 

This type-field is used by the record package in the translation of TYPE? 
expressions. 
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3. fields describes the structure of the record. Its exact interpretation 
varies with the record-type ; 

For RECORD, f ields is a list whose non-NIL literal atoms are taken as 
field-names to be associated with the. corresponding elements and 
tails of a list structure. NIL can be used as a place marker to fill 
an unnamed field, e.g. (A NIL B) describes a three element list, with 
B corresponding to the third element. 

For TYPERECORD, fields has the same meaning as for RECORD. However, 
since CAR of the datum contains an indicator signifying its "typo," 
the translation of the access/storage functions differ from those of 
RECORD. For example, for (TYPERECORD MSG (ID (FROM TO) . TEXT)), 
X:FROM translates as (CAADDR X), not (CAADR X). 



For ATOMRECORD declarations, fields is a list of property names p e.g. 
(ATOMRECORD (EXPR CODE MACRO BLKLIBRARYDEF ) ) . Accessing will be 
performed with getp, storing with put . 

For PROPRECORDp f ields is also a list of property names. Accessing 
is performed with get, storing with putl . 8g For example, 
(RECORD ENTRY (INPUT VALUE ID . PROPS) (PROPRECORD PROPS (^HISTORY* 
«LISPXPRINT* SIDE *GROUP« *ERROR*))) could be used to describe an 



36 



A new function (part of the record package), similar to put , which takes a 
list as its first argument, searches the list looking for an occurrence of 
the given property name ( its second argument) . If found, it replaces the 
next element with the new property value (its third argument),, otherwise 
adds the property name and property value to the list. 
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entry on the history list (see Section 22). 



For HASHRECORD (or HASHLINK ) , fields is usually just fleld-namo , i.e. 
an atom, and is the name by which the corresponding hash-value is 
referred to. For example, for (RECORD (A B • C) (HASHRECORD B FOO)), 
X:FOO translates as (GETNASH (CADR X)). If f ield-name is a list, it 
is interpreted as (field-name arrayname arraysize). In this case, 
arrayname indicates the hash-array to be used. For example, 
(HASHRECORD (CLISP CLISPARRAY) ) would permit the user to obtain the 
CLISP translation of X by simply writing X:CLISP. arraysize is used 
for initializing the hash array: if arrayname has not been 
initialized at the time of the declaration, it will be set to 
( HARRAY (OR arrayslze 100)). 

For ARRAYRECORD, fields is a list of field-names that are associated 
with the corresponding elements of the array. MIL can be used as a 
place marker for an unnamed field (element). Positive integers can be 
used as abbreviation for the corresponding number of Nils. For 
example, (ARRAYRECORD (ORG DEST NIL ID 3 TEXT) ) describes an eight 
element array, with ORG corresponding to the first element, ID to 
the fourth, and TEXT to the eighth. 

For DATATYPE, the user may specify data structures which are more 
compact and which can be accessed faster than if list structures were 
used. When the user declares a DATATYPE for the first time, the 
record package informs the garbage collector of the structure; the 



Note that (ATOMRECORD (FOO FIE) )) is equivalent to (RECORD (VALUE . PROPS) 
(PROPRECORD PROPS (FOO FIE))), the difference being in the translations. 
In the first case, X:FIE translates as (GETP X (QUOTE FIE)), , in the second 
case, as (GET (CDR X) (QUOTE FIE)). Note also that in the first case, if X 
is not a literal atom, INTERLISP (i.e.. getp ) will generate an error. 
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system then allocates storage space and a type number for that data 
type. 88 For DATATYPE record declarations, fields is a list of fiold 
specifications, where each specification is either f ieldname or 
( fieldname fleldtype ). If f ieldtype is omitted (or f ieldtype =POINTER ) 
then the field can contain a pointer to any arbitrary INTERLISP 
datum. Other options for f ieldtype are: 

BITS n field contains an n-bit unsigned integer. 

INTEGER or INT field contains a full word signed integer. 
FLOATING or REAL field contains a full word floating point number. 
HALFWORD or HALF field contains a half word signed integer. 

For example, the declaration 

(DATATYPE MESSAGE ( (FLG BITS 12) TEXT (CNT BITS 4) 
(DATE HALF) (PRIO REAL) HEADER) ) 

would define a data type MESSAGE which occupies in INTERLlSP-10 

three words of storage with two pointer fields, with 2 bits left 

over. 59 



For ACCESSFN (or ACCESSFNS), fields is a list of the form 
(field-name accessdefinition setdefinition), or a list of elements of 
this form, accessdefinition is a function of one argument, the datum, 
and will be used for accessing, setdefinition is a function of two 



The necessary support, at the system level, for user data types was written 
by D.C. Lewis. , 



Fields are allocated in such a way as to optimize the storage used, and not 
necessarily in the order specified. Thus in this example the first word 
would contain TEXT and HEADER (pointers are put together) ; the second PRIO; 
and the third, DATE in the left half and FLG and CNT in the right. 

Mote that to store this information in a conventional RECORD list 
structure, e.g. (RECORD MESSAGE (FLG TEXT CNT DATE PRIO . HEADER)), would 
take 5 words of list space and three number boxes (for FLG, DATE, and 
PRIO). 
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arguments, the datum and the new value, and is used for storing. ^° 
For example, (HASHRECORD F00) and (ACCESSFN (F00 GETHASH PUTHASH)) 
are equivalent; in both cases, X:F00 translates as (GETHASH FOO) . 
Similarly, (ACCESSFN (DEF GETD PUTO)) would permit defining functions 
by writing fnsDEF^def inition. 91 



4. {defaults and/or subfields} is optional. It may contain expressions of tho 
form: 

(1) field-name *• form - specifies the default value for f ield-name . 
Used by CREATE. 

(2) DEFAULT *■ form - specifies default value for every field not 
given a specific default via (1). 

(3) a subfield declaration ■- i.e. a record declaration of any of the 
above types. For subfield declarations, record-name is obligatory. 
Instead of identifying the declaration as with the case of top . level 
declarations, record-name identifies the parent field or record that 
is being described by the subfield declaration. It must be either the 
record-name of the immediately superior declaration, or one of its 
field-names (or else an error is generated). 

Subfields can be nested to an arbitrary depth. 

Mote that in some cases, it makes sense for a given field to have 



90 



Currently, an error is generated if CREATE is called with a record 
declaration containing an ACCES5FNS record-type. 



91 [ACCESSFN (DEF GETD (LAMBDA (FN DEF) (DEFINE (LIST (LIST FN DEF] would bo 
preferable to using putd. 



23.58 



more than one subfield declaration. For example, in 
(RECORD (A . B) (PROPRECORD B (F00 FIE FUM) ) ( HASHRECORO B C)), B is 
elaborated by both a PROPRECORD and HASHRECORO. Similarly, 
(RECORD (A B) (RECORD A (C D ) ) (RECORD A (FOO FIE))) is also 
acceptable, and essentially "overlays" (FOO FIE) and (C D) 0 i.e. 
X:FOO and X:C would be equivalent. In such cases, the first subfield 
declaration is the one used by CREATE, e.g. 

(RECORO X (A B) (RECORD A (C D)) (RECORD A (FOO FIE FUM)) ) will 
cause (CREATE X) to construct ( (NIL NIL) NIL) , not 
((NIL NIL NIL) NIL), as would be the case if the subfield declaration 
(RECORD A (C D) ) were removed. 

CREATE 

Record operations can be applied to arbitrary structures, i.e. structures 

created directly by user programs can be manipulated in a data-independent 

manner using record declarations . However, to be completely data-independent, 

new data should be created using the same declarations that define its data 

paths. This can be done by means of an expression of the form 

op 

(CREATE record-name . {assignments}), (assignments) is optional and may 
contain expressions of the following form: 

(1) field-name «• form specifies initial value for f ield-name , g3 



CREATE is not defined as a function. Instead, DWIM calls the appropriate 
function in the record package giving it the entire CREATE expression as an 
argument. The translation of the CREATE expression, i.e. the INTERL ISP 
form which is evaluated to construct the datum, is then stored elsewhere, 
as with iterative statements and pattern matches. 



The record package goes to great pain to insure that the order of 
evaluation in the translation is the same as that given in the original 
create expression. 
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(2) USING form 



specifies that for all fields not given a 



value by ( 1 ) , the value of the corresponding 



field in form is to be used. 



(3) COPYING form 



like USING except the corresponding values 



are copied ( copy ) . 



(4) REUSING form 



like USING, except that wherever possible , 



the corresponding structure in form is usod 



(similar to operation of subpair and sublis ) , 



For example, following (RECORD F00 (A B C)) P 

(CREATE FOO A-T USING X) translates as (LIST T (CADR X) (CADDR X)) v 

(CREATE FOO A*-T COPYING X)) as (LIST T (COPY (CADR X)) (COPY (CADDR X))), and 

(CREATE FOO A-T REUSING X) as (CONS T (CDR X)). 



A CREATE expression translates into an appropriate IN1TERLISP form using cons , 
list . put , putl , puthash, seta , etc., that creates the new datum with the 
various f ields initialized to the appropriate values. If values are neither 
explicitly specified, nor implicitly specified via USING or COPYING, the 
DEFAULT value in the declaration is used, if any, 94 otherwise NIL, 95 96 



For RECORD and TYPERECORD declarations with non-NIL defaults, all elements 
and named tails will be initialized; unnamed tails will not be initialized. 
For example, (RECORD FOO (A NIL B) DEFAULT-T) will cause (CREATE FOO) to 
construct (T T T) not (T T T . T). Of course. 

(RECORD FOO (A B . C) DEFAULT-T) will cause (CREATE FOO) to construct 
( T T . T) as expected. 



For PROPRECORD, initialization is only performed where necessary. For 
example, (RECORD FOO (A B) (PROPRECORD B (C D E ) ) ) would cause 

(CREATE FOO D-T) to construct (NIL (D T)), not (NIL (C NIL DTE NIL)). 
However, with the declaration (PROPRECORD FIE (HI J)) the expression 
(CREATE FIE) would still construct (H NIL), since a later operation of 
X:J*-T could not possibly change the instance of the record if it were NIL. 



For non-pointer fields in DATATYPE records, zero is used. 
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Implementation 

Record operations are implemented by replacing expressions of the form X:FOO by 
(FETCH FOO OF X), and X:F0O~Y by (REPLACE F00 OF X WITH Y), 97 and then storing 
the translation elsewhere, usually in a hash array, as described on page 23.31. 
Expressions involving data-paths, e.g. X:F00.FIE.A and X:F0Q.A*-19, are replaced 
by (FETCH (FOO FIE A) OF X) and (REPLACE (FOO A) OF X WITH 19) respectively. 
Translations of CREATE and TYPE? expressions are also stored elsewhere. 

The list of global record declarations currently in effect is stored as the 
value of the variable userreclst . Particular declarations may be edited by 
calling the function editrec , giving the record name (or the name of one of the 
fields), editrec calls the editor on a copy of all relevant declarations, and 
on exit redeclares those that have changed. Calling (EDITREC) allows the usor 
to edit all declarations. 

Records can also be declared local to a particular function by using a CLISP 
declaration, as described on page 23,37; all local record declarations override 
global ones . 

For both global and local records, the translation is computed using all CLISP 
declarations in effect as described on page 23.35, e.g. if the declaration 
UNDOABLE is in effect, /RPLACA, /RPLACD, /PUTHASH, etc. will be used. 93 

When the user redeclares a global record, the translations of all expressions 
involving that record are automatically deleted, 99 and thus will be recomputed 



CLISP also recognizes expressions input in this form. 

Currently, there are no UNDOABLE versions of the replace functions for 
DATATYPES. 



from clisparray . If the user is not using this method for storing 
translations, i.e. is instead using the CLI5P%_ method (page 23.33), those 
expressions already translated will remain as they are, (There is no 
practical way to locate them.) 
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using the new information. If the user changes a local record declaration, or 
changes some other CLISP declaration, e.g. STANDARD to FAST, and wishes the now 
information to affect record expressions already translated, he must make sure 
the corresponding translations are removed, usually either by CLISPIFYING or 
applying the ! DW edit macro. 



23.12 CLISPIFY 

Clispify converts INTERLISP expressions to CLISP. Note that the expression 
given to clispify need not have originally been input as CLISP, i.e., clispify 
can be used on functions that were written before CLISP was even implemented. 
Clispify is cognizant of declaration rules as well as all of the precedence 
rules. 100 For example, clispify will convert (IPLUS A (ITIMES B C) ) into A+B*C, 
but ( ITIMES A (IPLUS B C)) into A*(B+C) . 101 Clispify converts calls to the six 
basic mapping functions, MAP, MAPC, MAPCAR, MAPLIST, MAPCONC, and HAPCON, into 
equivalent iterative statements. It also converts certain easily recognizable 
internal PROG loops to the corresponding i.s. For example, 

— label (COND (pred ... forms ... (60 label))) ... 

becomes 

... label (WHILE pred DO ... forms ....) ... 102 



100 



101 



102 



clispify is table driven exactly the same as CLISP, so that if the user 
changes any precedence, or defines new operators, clispify "automatically" 
knows about it. — 

clispify also knows how to handle expressions consisting of a mixture of 
INJTERLISP and CLISP, e.g. (IPLUS A B«C) is converted to A+B«C, but 
(ITIMES A B+C) to (A*(B*C)). clispify handles such cases by first 
dv/imify ing the expression. 

clispify can convert all iterative statements input in CLISP back to CLISP, 
regardless of how complicated the translation was, because the original 
CLISP is saved. 
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Clispify is not destructive to the original INTERLISP expression, i.e. cl ispify 
produces a new expression without changing the original . u Clispify will not 
convert expressions appearing as arguments to NLAMBDA functions . 



The value of various global parameters affect the operation of clispify : 
clrflg 

The user can disable the : transformation by setting the variable cl : fig to 
NIL. This will prevent clispify from constructing any expression employing a : 
infix operator, e.g. (CADR X) will not be transformed to X:2. When cl : f Ig is 
T, clispify will convert to : notation only when the argument is atomic or a 
simple list (a function name and one atomic argument). If cl ;f lg is ALL, 
clispify will convert to : expressions whenever possible. The initial value of 
cl:f lg is T. 

clrenparsf lg 

Clispify will remove parentheses in certain cases from simple forms, whoro 
'simple' means a function name and one or two atomic arguments. For example, 
(COND ((ATOM X) --)) will CLISPIFY to (IF ATOM X THEN —). However, if 
clrenparsf lg is set to NIL, clispify will produce (IF (ATOM X) THEN — .). Note 
that regardless of the setting of this flag, the expression can be input in 
either form. The initial value of clremparsf lg is T. 

clispif ypackf lg 

clispifypackf lg affects the treatment of infix operators with atomic operands. 



The new expression may however contain some 'pieces 1 of the original, since 
clispify attempts to minimize the number of CONSes by not copying structure 
whenever possible. 



Except for those functions with property INFO, value EVAL such as nlsetq . 
resetlst , etc. clispify also contains built in information enabling it to 
process special forms such as prog , selectq , etc. 
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If clispifypackf Ig is T, clispify will pack these into' single atoms, e.g., 
(IPLUS A ( I TIMES B C)) becomes A+B*C. If clispifypackf Ig is NIL, no packing is 
done, e.g., the above becomes A^+JM^C. The initial value of clispifypackf Ig 
is T. 

f unnyatonlst 

Suppose the user has variables named A, B, and A*B. If clispify were to 
convert (ITIMES A B) to A*B, A*B would not translate back correctly to 
(ITIMES A B), since it would be the name of a variable, and therefore would not 
cause an error. The user can prevent this from happening by adding A*B to the 
list funnyatomlst . Then, (ITIMES A B) would clispify to A^_B. 

Mote that A*B's appearance on funnyatomlst would not enable DWIM/CLISP to 
decode A*B*C as (IPLUS A*B C); funnyatomlst is used only by clispify . Thus, if 
an identifier contains a CLISP character, it should always be separated (with 
spaces) from other operators. For example, if X* is a variable, the user 
should write (5ETQ X* form) in CLISP as X* «-form, not X*«~form, However, in 
general, it is best to avoid use of identifiers containing CLISP character 
operators as much as possible . 

clispif ypret ty fig 

If T, causes prettyprint to clispify all expressions before printing them (but 
not to redefine any functions), clispifyprettyf Ig is temporarily reset to T, 
using resetvar , when makefile is called with the option CLISPIFY, or when the 
file in question has property FILETYPE with value CLISP on its property list. 
clispifyprettyflg is initially NIL. 

« s & 

In addition to the above controls, disabling a CLISP operator (see cldisable , 
page 23.78) will also disable the corresponding CLISPIFY transformation . 
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Thus, if «- is "turned off", A<>B will not transform to (SETQ A B), nor vice 
versa . 

23.13 Dwimify 

Dwimify is effectively a preprocessor for CLISP. Dwimify operates by scanning 
an expression as though it were being interpreted, and for each form that would 
generate an error, calling DWIM to 'fix 1 it.^ 5 Thus the user will see the same 
messages, and be asked for approval in the same situations p as he would if the 
expression were actually run. If DWIM is unable to make a correction, no 
message is printed, the form is left as it was, and the analysis proceeds. 

Dwimify knows exactly how the interpreter works. It knows the syntax of prog s, 
selectgs , lambda expressions, setqs , et al. It knows that the argument of 
nlambdas are not evaluated. 106 It also knows how variables are bound. In the 
course of its analysis of a particular expression, dwimify builds a list of the 
bound variables from the LAMBDA expressions and PROGs that it encounters. It 
uses this list for spelling corrections , Dwimify also knows not to try to 
•correct 1 variables that are on this list since they would be bound if the 
expression were actually being run. However, note that dwimify cannot, a 
priori, know about variables that are used freely but would be bound in a 
higher function if the expression were evaluated in its normal contoxt . 
Therefore, dwimify will try to ■ '■correct' these variables. Similarly, dwimify 
will attempt to correct forms for which car is undefined, even when the form is 



Thus dwimify performs all DWIM transformations, not just CLISP 
transformations, i.e., it does spelling correction, fixes 8-9 errors, 
handles F/L, etc. 



The user can inform dwimify that an NLAMBDA function does evaluate its 
arguments (presumably by direct calls to oval ) , by including on its 
property list the property INFO with value EVAL. 
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not in error from the user's standpoint, but the corresponding function has 
simply not yet been defined. 



In most cases, an attempt to transform a form that is already as the user 
intended will have no effect (because there will be nothing to which that form 
could reasonably be transformed). However, in order to avoid needless calls to 
DWIM or to avoid possible confusion, the user can inform dwimify not to attempt 
corrections or transformations on certain functions or variables by adding 
them to the list nof ixfnslst or nof ixvarslst respectively.* 3 ^ 7 108 

Dwimify and dwimifyfns (used to dwimify several functions) maintain two 

internal lists of those functions and variables for which corrections wore 

unsuccessfully attempted. These lists are initialised to nof ixfnslst and 

nof ixvarslst . Once an attempt is made to fix a particular function or 

variable, and the attempt fails, the function or variable is added to the 

corresponding list, so that on subsequent occurrences (within this call to 

dwimify or dwimifyfns ), no attempt at correction is made. For example , if FOO 

calls FIE several times, and FIE is undefined at the time FOO is dwimif ied, 

dwimify will not bother with FIE after the first occurrence. In other words, 

once dwimify "notices" a function or variable, it no longer attempts to correct 
109 

il. Moreover, once dwimify "notices" such functions or variables, it 
subsequently treats them the same as though they were actually defined or set. 



107 

Mote that the user could achieve the same effect by simply setting tho 
corresponding variables, and giving the functions dummy definitions. 

1 OS 

Dwimify will never attempt corrections on global variables, i.e. variables 
that are a member of the list globalvars , or have the property GLOBALVAR 
with value T, on their property list. Similarly, variables declared to bo 
LOCALFREEVARS or SPECVARS in block declarations are automatically added to 
nof ixvarslst at compile time, so that they will not be 'corrected. 1 

1 09 

Dwimify and dwimifyfns also "notice" free variables that are set in the 
expression being processed. 
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Mote that these internal lists are local to each call to dwimify and 
dwimifyfns , so that if a function containing F000, a misspelled call to FOO, is 
dwimif led before FOO is defined or mentioned, if the function is dwimified 
again after FOO has been defined, the correction will be made. 

Note that the user can undo selected transformations performed by dwimify , as 
described in section 22. 

Compiling CLISP 

Since the compiler does not know about CLISP, in order to compile functions 
containing CLISP constructs, the definitions must first be dwimified . The user 
can automate this process in several ways: 

1) If the variable dwimif ycompflg is T, the compiler will always dwimify 
expressions before compiling them, dwimifycompf Ig is initially MIL. 

2) If a file has the property FILETYPE with value CLISP on its property list, 
tcompl , bcompl , recompile , and brecompile will operate as though dwimifycompf Ig 
is T and dwimify all expressions before compiling. 

3) If the function definition has a CLISP declaration (see page 23.35), 
including a null declaration, i.e., just (CLISP:), the definition will be 
automatically dwimified before compiling. 

Mote: tcompl , bcompl, recompile , and brecompile all scan the entire file before 
doing any compiling, and take note of the names of all functions that are 
defined in the file as well as the names of all variables that are set by 
adding them to nof ixfnslst and nof ixvarslst , respectively. Thus, if a function 
is not currently defined, but is defined in the file being compiled, when 
dwimify is called before compiling, it will not attempt to correct the function 
when it appears as car of a form. 
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Note: conpileuserfn (Section 18) is defined to call dwimify on iterative 
statements, as well as IF-THEN statements. Thus, if the only CLISP constructs 
in a function appear inside of iterative statements or IF statements, the 
function does not have to be dwimif ied before compiling. 

23. 14 Operation 

CLISP is a part of the basic INTERLISP system. Without any special 
preparations, the user can include CLISP constructs in programs, or type thorn 
in directly for evaluation (in eval or apply format), and when the "error 11 
occurrs, and DWIM is called, it will destructively**** transform the CLISP to 
the equivalent INTERLISP expression and evaluate the INTERLISP expression. 
User approval is not requested, and no message is printed. lil 

However, if a CLISP construct contains an error, an appropriate diagnostic is 
generated, and the form is left unchanged. For example, if the user writes 
(LIST X+Y*), the error diagnostic MISSING OPERAND AT X+Y* IN (LIST X*Y«) would 
be generated. Similarly, if the user writes (LAST^EL X) , CLISP knows that 
((IPLUS LAST EL) X) is not a valid INTERLISP expression, so the error 
diagnostic MISSING OPERATOR IN (LAST+EL X) is generated. (For example, tho 
user might have meant to say ( LAST*EL*X) . ) Note that if LAST*EL were the name 
of a defined function, CLISP would never see this form. 

Since the bad CLISP transformation might not be CLISP at all, for example, it 
might be a misspelling of a user function or variable, DWIM holds all CLISP 



CLISP transformations, like all DWIM corrections, are undoable. 

This entire discussion also applies to CLISP transformation initiated by 
calls to DWIM from dwimify . 



23.68 



error messages until after trying other corrections. If one of these succeeds, 
the CLISP message is discarded. Otherwise, if all fail, the message is printed 
(but no change is made). 1 ^ For example, suppose the user types (R/PLACA X Y). 
CLISP generates a diagnostic, since ((IQUOTIENT R PLACA) X Y) is obviously not 
right. However, since R/PLACA spelling corrects to /RPLACA, this diagnostic is 
never printed . 

If a CLISP infix construct is well formed from a syntactic standpoint, but one 
or both of its operands are atomic and not bound, it is possible that either 
the operand is misspelled, e.g., the user wrote X*YY for X*Y, or that a CLISP 
transformation operation was not intended at all, but that the entire 
expression is a misspelling. For example, if the user has a variable named 
LAST-EL, and writes (LIST LAST-ELL). Therefore, CLISP computes, but does not 
actually perform, the indicated infix transformation. DWIM then continues, and 
if it is able to make another correction, does so, and ignores the CLISP 
interpretation. For example, with LAST-ELL, the transformation 
LAST-ELL -> LAST-EL would be found. 

If no other transformation Is found, and DWIM is about to interpret a construct 
as CLISP for which one of the. operands is not bound, DWIM will ask the user 
whether CLISP was intended, in this case by printing 
LAST-ELL TREAT AS CLISP I 114 



112 



113 



Except that CLISP error messages are not printed on type-in. For example, 
typing X**Y will just produce a U.8.A. X**Y message. 

For the purpose of dwimifying , , 'not bound' means no top level value, not 
on list of bound variables built up by dwimify during its analysis of the 
expression, and not on nof ixvarslst , i.e., not previously seen. 



If more than one infix operator was involved in the CLISP construct, e.g., 
X+Y+Z , or the operation was an assignment to a variable already noticed, or 
treatasclispf lg is T (initially NIL), the user will simply be informed of 
the correction. Otherwise, even if DWIM was enabled in TRUSTING mode, the 
user will be asked to approve the correction. 
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The same sort of procedure is followed with 8 and 9 errors. For example , 
suppose the user writes F008*X where F008 is not bound. The CLISP 
transformation is noted, and DWIM proceeds. It next asks the user to approve 
F008*X -> FOO ( *X. (For example, this would make sense if the user has (or 
plans to define) a function named *X.) If he refuses, the user is asked 
whether F008*X is to be treated as CLISP. Similarly, if F008 were the name of 
a variable, and the user writes F0008*X, he will first be asked to approve 
F0008*X -> F000 ( XX, 116 and if he refuses, then be offered the F0008 -> F008 
correction . 

CLISP also contains provision for correcting misspellings of infix operators 
(other than single characters), IF words, and i.s. operators. This is 
implemented in such a way that the user who does not misspell them is not 
penalized. For example, if the user writes IF N*0 THEN 1 ELSSE N* (FACT. N-l ) 
CLISP does not operate by checking each word to see if it is a misspelling of 
IF, THEN, ELSE, or ELSE IF, since this would seriously degrade CLISP's 
performance on all IF statements. Instead, CLISP assumes that all of the IF 
words are spelled correctly, and transforms the expression to 
(COND ((ZEROP N) 1 ELSSE N*(FACT N-l))). Later, after DWIM cannot find any 
other interpretation for ELSSE, and using the fact that this atom originally 
appeared in an IF statement, DWIM attempts spelling correction, using 
(IF THEN ELSE ELSEIF) for a spelling list. When this is successful, DWIM 
•fails 1 all the way back to the original IF statement, changes ELSSE to ELSE, 
and starts over. Misspellings of AND, OR, LT, 6T, etc. are handled similarly. 

CLISP also contains many Do-What-I-Mean features besides spelling corrections. 
For example, the form (LIST *X Y) would generate a MISSING OPERATOR error. 



The 8-9 transformation is tried before spelling correction since it is 

empirically more likely that an unbound atom or undefined function 

containing an 8 or a 9 is a parenthesis error, rather than a spelling 
error . 
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However, (LIST -X Y) makes sense, if the minus is unary, so DWIM offers this 
interpretation to the user. Another common error, especially for new users,, is 
to write (LIST X*FOO(Y)) or ( LIST X^FOO Y) , where TOO is the name of a 
function, instead of (LIST X a (F00 Y)), Therefore, whenever an operand that is 
not bound is also the name of a function (or corrects to one), the above 
interpretations are offered. 



23.15 CLISP Interaction with User 

Syntactically and semantically well formed CLISP transformations are always 
performed without informing the user. Other CLISP transformations described in 
the previous section, e.g. misspellings of operands, infix operators, 
parentheses errors, unary minus - binary minus errors, all follow the same 
protocol as other DWIM transformations (Section 17). That is, if DWIM has been 
enabled in TRUSTING mode, or the transformation is in an expression typed in by 
the user for immediate execution, user approval is not requested, but the user 
is informed. However, if the transformation involves a user program, and 
DWIM was enabled in CAUTIOUS mode, the user will be asked to approve. If he 
says MO, the transformation is not performed. Thus, in the previous section, 
phrases such as "one of these (transformations) succeeds" and "the 
transformation LAST-ELL »> LAST-EL would be found" etc., all mean if the user 
is in CAUTIOUS mode and the error is in a program, the corresponding 
transformation will be performed only if the user approves (or dofaults by not 
responding). If the user says NO, the procedure followed is the same as though 
the transformation had not been found. For example, if A®B appears in the 



However, in certain situations, DWIM will ask for approval even if DWIM is 
enabled in TRUSTING mode. For example, the user will always be asked to 
approve a spelling correction that might also be interpreted as a CLISP 
transformation, as in LAST-ELL -> LAST-EL. 
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function F00, and B is not bound (and no other transformations are found) tho 
user would be asked 

A*B [IN F00] TREAT AS CUSP ? 117 
If the user approved, A*B would be transformed to ( ITIMES A B) , which would 
then cause a U.B.A. B error in the event that the program was being run 
(remember the entire discussion also applies to DWIMIFYing). If the user said 
NO, A*B would be left alone. 



23.16 CLISP Internal Conventions 



Note: the reader can skip this section and proceed to "Function and Variables" 
(page 23.75), unless he wants to add new operators, or modify the action of 
existing ones (other than by making declarations) . 

CLISP is almost entirely table driven by property lists for the corresponding 
infix or prefix operators. Thus it is relatively easy to add new infix or 
prefix operators or change old ones, simply by adding or changing selected 
property values . **** 

CLISPTYPE The property value of the property CLISPTYPE is the 

1 to 

precedence number of the operator: 1 ^ higher values 
have higher precedence, i.e. are tighter. Note that 



117 

The waiting time on such interactions is three times as long as for simple 
corrections, i.e., 3* dwimwait . 

1 18 

There is some built in information for handling minus, :, • , < , >, and 
i.e., the user could not himself add such 'special 1 operators, although he 
can disable them. 

Unless otherwise specified, the property is stored on the property list of 
the operator. 
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the actual value is unimportant, only tho value 
relative to other operators. For example, CLISPTYPE 
for :, t, and ft are 14, 6, and 4 respectively. 
Operators with the same precedence group left to right, 
e.g., / also has precedence 4, so A/B*C is (A/B)*C. 

An operator can have a different left and right 
precedence by making the value of CLISPTYPE bo a dottod 
pair of two numbers, e.g., CLISPTYPE of *■ is (8 . -12). 
In this case, car is the left precedence, and cdr the 
right, i.e., car is used when comparing with operators 
on the left , and cdr with operators on the right. For 
example, A*B«-C*D is parsed as A*(B«-(C<*D) ) because tho 
left precedence of «• is 8, which is higher than that of 
*■ which is 4. The right precedence of <> is -12, which 
is lower than that of ❖/which is 2. 

If the CLISPTYPE property for any infix operator is 
removed, the corresponding CLISP transformation is 
disabled, as well as the inverse CLISP'IFY 
transformation. 

The value of property UNARYOP must be T for unary 
operators. The operand is always on the right, i.e., 
unary operators are always pref ix operators . 

The value of property BROADSCOPE is T if the operator 
has lower precedence than INTERLISP forms, e.g., LT, 
EQUAL, AND, etc. For example, (FOO X AND Y) parses as 
((FOO X) AND Y). If the BROADSCOPE property were 
removed from the property list of AND, (FOO X AND Y) 
would parse as (FOO (X AND Y)). 
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LISPFN The value of the property LI5PFM is the name of tho 

function to which the infix operator translates. For 
example, the value of LISPFN for ? is EXPT, for ' 
QUOTE, etc. If the value of the property LISPFN is 
NIL, the infix operator itself is also the function 
e.g., AND, OR, EQUAL. 

SETFN If F00 has a SETFN property FIE, then (FOO ~)-X 

translates to (FIE X). For example, if the user 
makes ELT be an infix operator, e.g. by putting 
appropriate CLISPTYPE and LISPFN properties on tho 
property list of # then he can also make # followed by 
«• translate to SETA, e.g. X#N*-Y to (SETA X N Y), by 
putting SETA on the property list of ELT under the 
property SETFN. Putting (ELT) (i.e. list[ELT]) ) on tho 
property list of SETA under property SETFN will enable 
SETA forms to CLI5PIFY back to ELT's. 

CLISPINFIX The value of this property is the CL1SP infix to be 

used in CLISPIFYing. This property is stored on tho 
property list of the corresponding INTERLISP function, 
e.g., the value of property CLISPINFIX for EXPT is t, 
for QUOTE is 1 etc. 

Global declarations operate by changing the corresponding LISPFN and CLISPINFIX 
properties . 

clispchars is a list of single character operators that can appear 

in the interior of an atom. Currently these are: + , 
*V I \ t. : • <•' and >. 
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ciispcharray is a bit table of the characters on clispchars used for 

calls to strposl (see Section 10). ciispcharray is 
initialized by performing 

(SETQ CIISPCHARRAY (MAKEBITTABLE CLISPCHARS) ) . 

clispinf ixsplst is a list of infix operators used for spelling 

correction. 

As an example, suppose the user wants to make | be an infix character operator 
meaning OR. He performs: 

-(PUT (QUOTE |) (QUOTE CLISPTYPE) (GETP (QUOTE OR) (QUOTE CLISPTYPE))) 
-PUT( | LISPFN OR) 
-PUT( | BROADSCOPE T) 
-PUT(OR CLISPINFIX | ) 

*-SETQ(CLISPCHARS (CONS (QUOTE | ) CLISPCHARS)) 
«-SETQ( CLISPCHARRAY (MAKEBITTABLE CLISPCHARS)) 



23.17 CLISP Functions and Variables 

clispflg if set to NIL, disables all CLISP infix or prefix 

transformations (but does not affect IF/THEN/ELSE 
statements, or iterative statements). 

If clispf Ig sTYPE-IN, CLISP transformations are 
performed only on expressions that are typed in for 
evaluation, i.e. not on user programs. 

If clispf Ig sT, CLISP transformations are performed on 
all expressions. 

The initial value for clispflg is T. clispify ing 
anything will cause clispflg to be set to T. 
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clisparray 



hash array used for storing translations . clisparray 
is checked by faulteval and faultapply on erroneous 
forms before calling DWIM, and by the compiler. 



gives x the translation tran . If clisparray is not 
NIL* uses hashing scheme, otherwise uses CLISP%_ 
scheme. See page 23.31 -page 23.35. 

list of functions that dwimify will not try to correct. 
See page 23.66. 

list of variables that dwimify will not try to correct. 
See page 23.66. 

If nospellf Ig is T, dwimify will not perform any 
spelling corrections. The initial value of nospel If lg 
is NIL. 

For example, setting nospellf Ig to T might be useful in the case where a file 
known to contain no misspellings had been clispif ied, and was now being 
dwimif ied, e.g. as it was being compiled. With nospellf lg *T, DWIM would not 
waste time trying to spelling correct the free variables. Note that if all of 
the free variables are known, the same effect could be achieved by simply 
adding them to nof ixvarslst . 

dwimify[x;l] dwimif ies x» i.e., performs all corrections and 

transformations that would be performed if x were run. 
If x is an atom and 1 is NIL, x is treated as the name 
of a function, and its entire definition is dwimified. 

Otherwise, if x is a list or 1 is not NIL, x is the 
expression to be dwimif ied. If 1 is not NIL, it is the 



clisptran[x; tran] 



nof ixfnslst 



nof ixvarslst 



nospellf Ig 
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edit push-down list leading to x, and is used for 
determining context, i.e., what bound variables would 
be in effect when x was evaluated, whether x is a form 
or sequence of forms, e.g., a cond clause, etc. 

dwimifyfns[fns] nlambda, nospread. Dwimifies each function on f ns . If 

fns consists of only one element, the value of car[fns] 
is used, e.g., dwimifyfns[FOOFNS]. Every 30 seconds, 
dwimifyfns prints the name of the function it is 
processing, a la prettyprint . 

dwimifycompf Ig if T, dwimify is called before compiling an expression. 

See page 23.67. 



clispdec[declst] puts into effect the declarations in declst . clispriec 

performs spelling corrections on words not recognized 
as declarations, clispdec is undoable . 

clispify[x;l] clispifies x« If x is an atom and 1 is NIL, x is 

treated as the name of a function, and its definition 
(or EXPR property) is clispified. After clispify has 
finished, x is redefined (using /PUTD) with its new 
CLISP definition. The value of clispify is x. If x is 
atomic and not the name of a function, spelling 
correction is attempted. If this fails, an error is 
generated. 

If x is a list, or 1 is not NIL, x itself is the 



If x is an iterative statement and 1 is NIL, dwimify will also print the 
translation, i.e. what is stored in the hash array. 
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expression to be clispif led. If 1 is not NIL, it is 
the edit push-down list leading to x and is used to 
determine context as with dwimify, as well as to obtain 
the local declarations, if any. The value of clispif y 
is the clispified version of x. 

See earlier section on CLISPIFY for more details, 

nlambda, nospread. Calls clispify on each member of 
fns under errorset protection. If fns consists of only 
one element, the value of car[fns] is used, e.g., 
ciispifyfns[FOOFNS]. Every 30 seconds, clispif yfns 
prints the name of the function it is working, a la 
prettypriht . Value is list of functions clispify ed, 

disables oj>, e.g. cldisable[»] makes - be just another 
character. cldisable can be used on all CLISP 
operators, e.g. infix operators, prefix operators, 
iterative statement operators, etc. cldisable is 
undoable. 

affects handling of translations of IF | THEN | ELSE 
statements. If T, the translations are stored 
elsewhere, and the (modified) CLISP retained. If NIL, 
the corresponding COND expression, replaces the CLISP, 
clispiftranflg is initially NIL. See page 23.31. 

If T, informs dwimify to (re)translate all expression 
which have remote translations, either in hash array or 
using CLI5P%. Initially NIL. 
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cl:flg 



affects ciispify »s handling of forms beginning with 
car , cdr , ... cddddr , as well as pattern match and 
record expressions. See page 23.63. 



clremparsf Ig 



affects clispify 's removal of parentheses from "small" 
forms. See page 23.63. 



clispifypackf Ig 



if T p informs clispify to pack operator and atomic 
operands into single atoms; if NIL* no packing is done. 
See page 23,63. 



clispifyprettyf lg 



if non-NIL, causes prettyprint to CLISPIFY selected 
function definitions before printing them according to 
the following interpretations of clispf ifyprettyf lg : 



ALL 

T, EXPRS 
CHANGES 
a list 



all functions 

functions currently defined as 
exprs 

functions marked as having been 
changed 

a member of that list ■ 



clispifyprettyf lg is (temporarily) reset to T when 
makefile is called with the option CLISPIFY, and reset 
to CHANGES when the file being dumped has the property 
FILETYPE value CLISP. clispifyprettyf lg is initially 



NIL. 
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prettytranf lg 



If T, causes prettyprint to print translations instead 
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If clispifyprettyf lg is non-NIL, and the only transformation performed by 
DWIM are well formed CLISP transformations, i.e. no spelling corrections, 
the function will not be marked as changed, since it would only have to bo 
re-clispif ied and re-prettyprinted when the file was written out. 
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of CLISP expressions.. This is useful for creating a 
file for compilation, or for exporting to a LISP system 
that does not have CLISP. prettytranf lg is 
(temporarily) reset to T when makef lie is called with 
the option NOCLISP. If prettytranf lg is CLI5P7,_, both 
the CLISP and translations are printed in appropriate 
form. For more details, see page 23.34. prettytranf lg 
is initially NIL. 

PPT is both a function and an edit macro for prettyprinting 

translations. It performs a PP after first resetting 
prettytranf lg to T, thereby causing any translations to 
be printed instead of the corresponding CLISP. 

CLISP: edit macro that obtains the translation of the correct 

expression, if any, from clisparray , and calls e elite on 
it . 

funnyatomlst list of identifiers containing CLISP operators. Used 

by clispify to avoid accidentally constructing a user 
identifier, e.g., ( ITIMES A B) should not become A®B if 
A*B is the name of a PROG variable/ See page 23.64. 

CL edit macro. Replaces current expression with 

CLISPIFYed current expression. Current expression can 
be an element or tail. 

DW edit macro. DWIMIFYs current expression, which can be 

an element (atom or list) or tail. 

Both CL and DW can be called when the current expression is either an element 
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or a tail and will work properly. Both consult the declarations in the 
function being edited, if any, and both are undoable. 

lowercase[ f lg] If f Ig sT, lowercase makes the necessary internal 

modifications so that clispify will use lower case 
versions of AND, OR, IF, THEN , ELSE, ELSE IF, and all 
i»s. operators. This produces more readable output. 
Note that the user can always type in either upper or 
lower case (or a combination), regardless of the action 
of lowercase 

If fl2 a NIL, clispify will use uppercase versions of 
AND, OR, at al. The value of lowercase is it's previous 
•setting*. Lowercase is undoable. The initial setting 4 
for lowercase is T. 
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Appendix 1 

Transor 

Introduction 

transor is a LISP-to-LISP translator intended 'to- help the. user who has a 
program coded in one dialect of -LISP and Irishes to carry it over to another. 
The user loads transor along with a file of transformations, These 
transformations describe the differences between the two LISPs, expressed in 
terms of IMTERliSP editor commands needed to convert the old to new, i.e. to 
edit forms written in the source dialect to make them suitable for the target 
dialect. transor then sweeps through the user 's program and. applies the edit 
transformations, producing an object, file for the target system. In addition, 
transor produces a file of translation notes p which ■ catalogs the major changes 
made in the code as well as the forms that require further attention by the 
user. Operation-ally, therefore, transor is a facility for conducting massive 
edits, and may be used for any purpose which that may suggest. 

Since the edit transformations are fundamental to this process, let us begin 
with a definition and some examples. A transformation is a list of edit 
commands associated with a literal atom, usually a function name. transor 
conducts a sweep through the user's code, until it finds a form whose car is a 
literal atom which has a transformation. The sweep then pauses to let the 
editor execute the list of commands before going on. For example, suppose the 
order of arguments for the function tconc must be reversed for the target 
system. The transformation for tconc would then be: ( (SW 2 3)) . When the 

. ' .. . I 
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sweep encounters the form (TCONC X (F00) ) , this transformation would be 
retrieved and executed, converting the expression to ( TCONC (FOO) X). Then the 
sweep would locate the next form, in this case (FOO), and any transformations 
for f oo would be executed, etc. 

Most instances of tconc would be successfully translated by this 
transformation. However, if there were no second argument to tconc , e.g. the 
form to be translated was (TCONC X), the command (SW 2 3) would cause an error, 
which transor would catch. The sweep would go on as before, but a note would 
appear in the translation listing stating that the transformation for this 
particular form failed to work. The user would then have to compare the form 
and the commands, to figure out what caused the problem. One might, however, 
anticipate this difficulty with a more sophisticated transformation: 
((If (## 3) ((SW 2 3)) ((-2 NIL)))), which tests for a third element and does 
(SW 2 3) or (-2 NIL) as appropriate. It should be obvious that the translation 
process is no more sophisticated than the transformations used. 

This documentation is divided into two main parts. The first describes how to 
use transor assuming that the user already has a complete set of 
transformations. The second documents transorset , an interactive routine for 
building up such sets, transorset contains commands for writing and editing 
transformations, saving one's work on a file, testing transformations by 
translating sample forms, etc. 

Two transformations files presently exist for translating programs into 
IMTERLISP . <LISP>SDS940.XFORMS is for old BBN LISP (SDS 940) programs, and 
<LISP>LISP16.XF0RMS is for Stanford AI LISP 1.6 programs, A set for LISP 1.5 
is planned. 
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Using Transor 

The first and most exasperating problem in carrying a program from on© 
implementation to another is simply to get it to read in. For example P SRI 
LISP uses / exactly as INTERLISP uses %, i.e. as an escape character. The 
function prescan exists to help with these problems: the user uses prescan to 
perform an initial scan to dispose of these difficulties, rather than 
attempting to transor the foreign sourcefiles directly. 

prescan copies a file, performing character-for-cbaracter substitutions. It is 
hand-coded and is much faster than either readc's or text-editors. 

prescan[f ilejcharlst] Makes a new version of file , performing 

substitutions according to charlst . Each element 
of charlst must be a dot*pair of two character 
codes B (OLD . NEW) . 

For example, SRI files are prescan 'ed with charlst a ((37 .47) (47 . 37) ) , 
which exchanges slash (47) and percent-sign (37). 

The user should also make sure that the treatment of doublequotes by the source 
and target systems is similar. In 1NTBRL1SP, an unmatched double-quote (unless 
protected by the escape character) will cause the rest of the file to read in 
as a string. 

Finally, the lack of a STOP at the end of a file is harmless, since transor 
will suppress END OF FILE errors and exit normally. 

Translating 

transor is the top-level function of the translator itself, and takes one 
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argument, a file to be translated. The file is assumed to contain a sequence 
of forms, which are read in, translated, and output to a file called file, IRAN. 
The translation notes are meanwhile output to f ile.LSTRAN, Thus the usual 
sequence for bring a foreign file to INTERLISP is as follows; prescan the file; 
examine code and transformations, making changes to the transformations if 
needed; transor the file; and clean up remaining problems, guided by the notes. 
The user can now make a pretty file and proceed to exercise and check out his 
program. To export a file, it is usually best to transor it, then prescan it, 
and perform clean-up on the foreign system where the file can be loaded, 

transor[ sourcef ile] Translates sourcef ile. Prettyprints translation 

on file.TRAN: translation listing on file , LSTRAN . 

transorform[ form] Argument is a LISP form. Returns the 

(destructively) 'translated form. The translation 
listing is dumped to the primary output file, 

transorfnst fnlst] Argument is a list of function names whose 

interpreted definitions are destructively 
translated. Listing to primary output file. 

transform and transorfns can be used to translate expressions that are already 
in core, whereas transor itself only works on files. 

The Translation Notes 

The translation notes are a catalog of changes made in the user's code, and of 
problems which require, or may require, further attention from the user. This 
catalog consists of two cross-indexed sections: an index of forms and an index 
of notes. The first tabulates all the notes applicable to any form, whereas 
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the second tabulates all the forms to which any one note applies. Forms appear 
in the index of forms in the order in which they were encountered, i.e. the 
order in which they appear on the source and output files. The index of notes 
shows the name of each note, the entry numbers where it was used, and its text, 
and is alphabetical by name. The following sample was made by translating a 
small test file written in SRI LISP. 
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LISTING FROM TRANSORING OF FILE TESTFILE . ; 5 
DONE ON 1- NOV- 71 20:10:47 



INDEX OF FORMS 

1 . APPLY/EVAL at 
[DEFINEQ 

(FSET (LAMBDA & 

(PROG . . .3. . . 

(SETQ Z (COND 

( (ATOM (SETQ --)) 



- 3 
2. APPLY/EVAL at 
[DEFINEQ 

(FSET (LAMBDA & 
(PROG 



(COND 

( (ATOM (SETQ Y (NLSETQ "(EVAL W)"))) 

--)) 

--)) 



3 



.3 . . • 
(SETq'z (COND 

((ATOM (SETQ --)) 
(COND 

((ATOM (SETQ --)) 

"(EVAL (NCONS W))") 
--)) 

--)) 



3. MACHINE-CODE at 
[DEFINEO 

(LESS1 ( LAMBDA & 

(PROG ...3.. 
( COND 



3 



((NOT (EQUAL (SETQ X2 "(OPENR (MAKNUM & -))" 
) 

")) 

--)) 



A. MACHINE-CODE at 
[DEFINEO 

(LESS1 (LAMBDA & 

(PROG ... .3. . . 
(COND 
. . .2 . . . 

( (NOT ' (EQUAL & (SETQ Y2 

"(OPENR (MAKNUM & --))"))) 

-->■) 



INDEX OF NOTES 



APPLY/EVAL at 1, 2. 

TRANSOR will translate the arguments of the APPLY or EVAL expression, but 
the user must make sure that the run-time evaluation of the arguments returns a 
BBN-compat1ble expression. 
MACHINE-CODE at 3, 4. 

Expression dependent on machine-code. User must recode. 
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The translation notes are generated by the transformations used, and therefore 
reflect the judgment of their author as to what should be included. 
Straight!" orv/ard conversions arc usually made without comment; for example, the 
DEFPROP's in this file were quietly changed to DEFII^EQ's. transor found four 
noteworthy forms on the file, and printed an entry for each in the index of 
forms, consisting of an entry number , the name of the note, and a printout 
showing the precise location of the form. The form appears in double-quotes 
and is the last thing printed, except for closing parentheses and dashes. An 
ampersand represents one non-atomic element not shown, and two or more elements 
not shown are represented as „.,n..., where n is the number of elements. Note 
that the printouts describe expressions on the output file rather than the 
source file; in the example, the DEFPROP's of SRI LISP have been replaced' with 
DEFINEQ 8 s . 

Errors and Messages 

transor records its progress through the source file by teletype printouts 
which identify each expression as it is read in. Progress within large 
expressions 9 such as a long DEFINEQ, is reported every three minutes by a 
printout showing the location of the sweep. 

If a transformation fails, transor prints a diagnostic to the teletype which 
identifies the faulty transformation p and resumes the sweep with the next form. 
The translation notes will identify the form which caused this failure, and the 
extent to which the form and its arguments were compromised by the error. 

If the transformation for a common function fails repeatedly, the user can type 
control-H. When the system goes into a break P he can use transorset to repair 
the transformation p and even test it out {see TEST command, page Ai.il). He 
may then continue the main translation with OKc 
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Transorset 



To use transorset , type transorset C) t© INTERLISP, transorset will respond 
with a * sign, its prompt character, and await input. The user is now in an 
executive loop which is like evalqt with some extra context and capabilities 
intended to facilitate the writing of transformations* transorset will thus 
progress apply and eval input, and execute history commands just as evalqt 
would. Edit commands, however; are interpreted as additions to the 
transformation on which the user is currently working* transorset always saves 
on a variable named currentfn the name of the last function whose 
transformation was altered or examined by the user, currentfn thus represents 
the function whose transformation is currently being worked on. Whenever edit 
commands are typed to the * sign, transorset will add them to the 
transformation for currentfn . This is the basic mechanism for writing a 
transformation. In. addition, transorset contains commands for printing out a 
transformation, editing a transformation, etc., which all assume that the 
command applies to currentfn if no function is specified. The following 
example illustrates this process. 
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<-TRANSORSET( ) 

❖ FN TCONC 
TCOHC 

❖ (SW 2 3) 

❖TEST (TCONC A B) 
P 

(TCONC B A) 
❖TEST (TCONC X) 

TRANSLATION ERROR: FAULTY TRANSFORMATION 
TRANSFORMATION: ((SW 2 3)) 
OBJECT FORM: (TCONC X) 



1. TRANSFORMATION ERROR AT 
"(TCONC X)" 



(TCONC X) 

❖(IF (## 3) ((SW 2 3)) ((-2 NIL] 

❖SHOW 

TCONC 

[(SW 2 3) 
(IF (## 3) 

((SW 2 3)) 
((-2 NIL] 

TCONC 

❖ERASE 

TCONC 

❖REDO IF 

❖SHOW 

TCONC 

[(IF (## 3) 

((SW 2 3)) 

((-2 NIL] 

TCONC 
❖ TDST 
"TEST 

(TCONC NIL X) 

❖ 
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In this example, the user begins by using the FN command to set currentfn to 
TCONC [1]. He then adds to the (empty) transformation for tconc a command to 
switch the order of the arguments [2] and tests the transformation [3] . His 
second TEST [4] fails, causing an error diagnostic [5] and a translation note 
[6], He writes a better command [7] but forgets that the original SW command 
is still in the way [8]. He therefore deletes the entire transformation [9] 
and redoes the IF [10], This time, the TEST works [11]; 

Transorset Commands 

The following commands for manipulating transformations are all lispxmacros 
which treat the rest of their input line as arguments. All are undoable. 

FN Resets currentfn to its argument, and returns the 

new value. In effect FN says you are done with 
the old function (as least for the moment) and 
wish to work on another. If the new function 
already has a transformation, the message 
(OLD TRANSFORMATIONS) is printed, and any 
editcommands typed in will be added to the end of 
the existing commands. FN followed by a carriage 
return will return the value of currentfn without 
changing it. 

SHOW Command to prettyprint a transformation. SHOW 

followed by a carriage return will show the 
transformation for currentfn , and return currentfn 
as its value. SHOW followed by one or more 
function names will show each one in turn, reset 
currentfn to the last one, and return the new 
value of currentfn. 
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EDIT Command to edit a transformation . Similar to SHOW 

except that instead of prettyprinting the 
transformation, EDIT gives, it to edit©. The user 
can then work on the transformation until he 
leaves the editor with OK, 

ERASE Command to deists a transformation. Otherwise 

similar to SHOR- 
TEST Command for checking out transformations. TEST 

takes one argument* a form for translation . The 
translation notes, if any, are printed to the 
teletype, but in an abbreviated format which ' omits 
the index of nptes. The . value returned is the 
translated form. TEST saves a copy of its 
argument on the free variable testf orm , and if no" 
argument is given, it uses test form, io®* tries 
the previous test again. 

DUMP Command to save your work on a file; DUMP takes 

one' argument,- a filename/ The argument is saved 
on tho variable dump file, so that if no argument 
is provided,-- a new version of the previous file 
will be created . 

The DUMP command creates files by makefile . Normally f ileFNS will be unbound, 
but the user may set it himself; functions called from a transformation by the 
E command may be saved in this way. DUMP makes sore that the necessary command 
is included on the f ileVARS to save the y$er 9 s transformations . The user may 
add anything else to his fileVAHS that he wishes. When a transformation file 
is loaded, all previous transformations are erased unless the variable merge is 
set to T. 
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EXIT 



transorset returns Hll* 



The REMARK Feature 

The translation notes are generated by those transformations that are actually 
executed via an editmacro called REMARK. REMARK takes one argument, the name 
of a note. When the macro is executed, it saves the appropriate information 
for the translation notes, and adds one entry to the index of forms. The 
location that is printed in the index of forms is the editor's location when 
the REMARK macro is executed. 

To write a transformation which makes a new note, one must therefore do two 
things: define the note, i.e. choose a new name and associate it with the 
desired text; and call the new note with the REMARK macro, i.e. insert the edit 
command (REMARK name) in some transformation. The NOTE command r . described 
below, is used to define a new note. The call to the note may be added to a 
transformation like any other edit command. Once a note is defined, it may be 
called from as many different transformations as desired. 

The user can also specify a remark with a new text, without bothering to think 
of a name and perform a separate defining operation, by calling REMARK with 
more than one argument, e.g. (REMARK text-of-remark) . This is interpreted to 
mean that the arguments are the text, transorset notices all such expressions 
as they are typed in, and handles naming automatically; a new name is 
generated 1 and defined with the text provided, and the expression itself is 
edited to be (REMARK generated-name) . The following example illustrates the 
use of REMARK. 



The name generated is the value of currentfn suffixed with a colon, or with 
a number and a colon. 
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~TRANSORSET( ) 

+HOTE GREAT ERP/LESSP (BBN'S GREATERP AND LESSP ONLY [1] 
TAKE TWO ARGUMENTS , WHEREAS SRI'S FUNCTIONS TAKE AN 
INDEFINITE NUMBER . AT THE PLACES NOTED HERE. THE SRI CODE 
USED MORE THAN TWO ARGUMENTS. AND THE USER MUST RECODE . ] 

GREATERP /LESSP 

♦ FN GREATERP 
GREATERP 

♦ (IF (IGREATERP (LENGTH (#s>))3) NIL ( ( REMARK GREATERP/LESSP ] [2] 

+FH LESSP 
LESSP 

♦ REDO IF [3] 

♦ SHOW 
LESSP 

[(IF (IGREATERP (LENGTH (##)) 
3) 

NIL 

( ( REMARK GREATERP/LESSP] 

LESSP 
♦FN ASCII 

(OLD TRANSFORMATIONS) 
ASCII 

+ ( REMARK ALTHOUGH THE SRI FUNCTION ASCII IS IDENTICAL [4] 
TO THE BBN FUNCTION CHARACTER, THE USER MUST MAKE SURE THAT 
THE CHARACTER BEING CREATED SERVES THE SAME PURPOSE ON BOTH 
SYSTEMS , SINCE THE CONTROL CHARACTERS ARE ALL ASSIGNED 

DIFFRENTLY.] 

+SHOW [5] 
ASCII 

( ( 1 CHARACTER) 
(REMARK ASCII:)) 
ASCII 

♦NOTE ASCII: [6] 

EDIT 

"NTH -2 

"P 

... ASSIGNED DIFFRENTLY.) 
"(2 DIFFERENTLY.) 

OK 

ASCII: 

+ 



A1.13 



In this example , the user defines a note named 6REATERP/LESSP by using the NOTE 
command [ 1 ], and writes transformations which call this note whenever the sweep 
encounters a GREATER? or LESSP with more than two arguments [2-3] . Next, the 
implicit naming feature is used [4] to add a REMARK command to the 
transformation for ASCII, which has already been partly written. The user 
realizes he mistyped part of the text, so he uses the SHOW command to find the 
name chosen for the note [5], Then he uses the NOTE command on this name, 
ASCII : , to edit the note [6], 

NOTE First argument is note name and must be a literal 

atom- If already defined, NOTE edits the old 
texts otherwise it defines the name, reading the 
text either from the rest of the input line or 
from the next line. The text may b® given as a 
line or as a list. Value is name of note. 

The text is actually stored, as a comment, i.e. a * and XX. are added in front 
when the note is first defined. The text will therefore be lower-cased the 
first time the user DUMPS (see Section 14). 

DELNOTE Deletes a note completely (although any calls to 

it remain in the transformations). 

Controlling the Sweep 

transor 's sweep searches in print-order until it finds a form for which a 
transformation exists. The location is marked, and the transformation is 



On the global list usernotes. 
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executed. The sweep then takes ov©r again* beginning from the marked location, 
no matter where the last command of the transformation left the editor. User 
transformations can therefore move around freely to examine the context, 
without worrying about confusing the translator. However, there are many cases 
where the user wants his transformation to guide the sweep, usually in order to 
direct the processing of special forms and FEXPR's. For example, the 
transformation for QUOTE has only one objective: to tell the sweep to skip over 
the argument to QUOTE, which is (presumably) not a LISP form. MLAM is an 
editmacro to permit this. 

N LAM An atomic editmacro which sets a flag which causes 

the sweep to skip the arguments of the current 
form when the sweep resumes. 

Special forms such as eond, prog, selectq , etc., present a more difficult 
problem- For example, (COND (A B)) is processed just like (FOO (A B)): i.e. 
after the transformation for cond finishes, the sweep will locate the "next 
form," (A B), retrieve ■ the transformation for the function A, if any, and 
execute it. Therefore, special forms must have transformations that preempt 
the sweep and direct the translation themselves. The following two atomic 
editmacros permit such transformations to process their forms, translating or 
skipping over arbitrary subexpressions as desired. 

OOTHIS Translates the editor's current expression, 

treating it as a single form. 

DOTHESE Translates the editor's current expression, 

treating it as a list of forms. 
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For example; a transformation for setg might be (3 DOTHIS). This translates 
the second argument to a setg without translating the first. For cond, one 
might write (1 (LPQ NX DOTHESE)), which locates each clause of the COND in 
turn, and translates it as a list of forms, instead of as a single form. 

The user who is starting a completely new set of transformations must begin by 
writing transformations for all the special forms. To assist him in this and 
prevent oversights, the file <LISP>SPECIAL.XFORNS contains a set of 
transformations for LISP special forms, as well as some other transformations 
which should also be included. The user will probably have to revise these 
transformations substantially, since they merely perform sweep control for 
IMTERLISP, i.e. they make no changes in the object code. They are provided 
chiefly as a checklist and tutorial device, since these transformations are 
both the first to be written and the most difficult* especially for users new 
to the IMTERLISP editor. 

When the sweep mechanism encounters a form which is not a list, or a form car 
of which is not an atom, it retrieves on© of the following special 
transformations. 

NLISTPCOMS Global value is used as a transformation for any 

form which is not a list. 

For example, if the user wished to make sure that all strings were quoted, he 
might set nlistpcoms to 

((IF (STRINGP (##)) ((ORR ((- QUOTE) )( (MBD QUOTE)))) NIL) ) . 



Recall that a transformation is a list of edit commands. In this case, 
there are two commands, 3 and OOTHIS. 
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LAMBDACOiiS Global value is used as a transformation for any 

form, car of which is not an atom. 

These variables are initialised by <LISP>SPECIAL.XFORNS and are saved by the 
DUMP commando nlistpcoms is initially NIL, making it a NOP. lambdacoms is 
initialized to check first for open LAMBDA expressions, processing them without 
translation notes unless the expression is badly formed. Any other forms with 
a non-atomic car are simply treated as lists of forms and are always mentioned 
in the translation notes. The user can change or add to this algorithm simply 
by editing or resetting lambdacoms . 



A1.17 



Index for Section Al 



Page 
Numbers 

CURREHTFN (transor variable) . . . . . A1.8 

DELNOTE (transor command) . . . At . 14 

DOTHESE (transor command) ....................... Ai.15 

DOTHIS (transor command) ... .... Al • 15 

DUMP (transorset command) At. 11 

EDIT (transorset command) Al.lt 

ERASE ( transorset command) Al . 11 

EXIT (transorset command) Al • 12 

FM (transorset command) ALIO 

LAMBDACOMS (transor command) Al . 17 

NLAM (transor command) Ai.15 

NLISTPCOMS (transor command) A1.16 

NOTE (transor command) ...... ...v. Al. 12,14 

PRESCAN[ FILE ;CHARLST] Al .3 

REMARK (transor command) At. 12 

SHOW (transorset command) Al .10 

TEST (transorset command) Al.il 

translation notes Al.4-7 

TRANSOR[SOURCEFILE] . . Al ,3-4 

TRANSOR Al.1-17 

transor sweep . ♦ Al . 14 

TRANSORFNS A1.4 

TRANSORFORM A1.4 

TRANSORSETE3 Ai.2,8 



INDEX. Al • 1 



Appendix 2 



The INTERL1SP Interpreter 

The flow chart presented below describes the operation of the INTERLISP 
interpreter, and corresponds to the m-expres$ion definition of the LISP 1.5 
interpreter to be found in the LISP 1.5 manual, [McCl ]• Note that car of a 
form must be a function; it cannot evaluate to a function. 

If car of a form is atomic P its function cell must contain 

(a) an S-expression of the form (LAMBDA . ..) or (NLAMBDA or 

(b) a pointer to compiled code; or 

(c) a SUBR definition (see Section 8); 
Otherwise the form is considered faulty. 

If car of a form is an S-expression beginning with LAMBDA or WLAMBDA, the 
S-expression is the function. If car of the form begins with FUNARG , the 
funarg mechanism -is invoked (see Section 11). Otherwise the form is faulty. 
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YES 


CALL 




FEXPR 



CAOR C 
IS FN, 
CADDR C 
SPECIFIES 
BINOINGS 



ENTER EVA L WITH FORM 




SET D 




CONTENTS 


OF 


DEFINITION 


CELL 



RETURN 
BINDING 




RETURN 
FAULT EVAL [FORM] 



YES 



CALL SUBR, 
COMPILED CODE, 
OR EXPR 



JL 



RETURN 
FAULTEVAL [FORM] 



FIGURE A2-S 



Note: variables c and d are for description onlys they are not actually bound 
as variables. 
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Control Characters 



Several teletype control characters are available to the user for communicat ing 
directly to 1NTERU5P, i.e., not through the read program. These characters 
are enabled by IMTERL1SP as interrupt characters, so that JNTERLISP immediately 
'sees' the - characters, and takes the corresponding action as soon as possible. 
For example, control characters are available for aborting or interrupting a 
computation, changing the printlevel, etc. This section summarizes the action 
of these characters, and references the appropriate section of the manual where 
a more complete description may be obtained. Section 16 describes how these 
interrupt characters can be disabled and/or redefined^ as well as how the usor 
can define his own new interrupt characters. 



Control Characters Affecting the Flow of Computation 

1. control-H (interrupt) at next function call, INTERLISP goes into 

a break. Section 16. 

2. control-B (break) computation is stopped, stack backed up to the 

last function call, and a break occurs. Section 16. 

3. control-E (error) computation is stopped, stack backed up to the 

last errorset p and Mil returned as its value. Section 

16. : 

4. control-D (reset) computation is stopped, control returns to 

evalq-t « 

5. control-C In iNTERLlSP-10, computation is stopped, control 

returns to TEWEX. Program can always,, be continued 
without any ill effect with TENEX COMTIMUE command. 



If typed during a garbage collection the action of control-B, control-E, and 
control~D is postponed until the garbage collection is completed. 



Typing control-E and control-D causes IWTERLISP t© clear and save the input 
buffers. Their contents can usually be recovered via the SBUFS (alt-modeBUFS) 
command, as described in Section 22. 



I/O Control Characters 

1. rubout clears teletype input buffer. For example, rubout 

would be used if the user typed ahead while in a 
garbage collection and then changed his mind. Section 
2. A bell is rung when the buffer has been cleared, so 
that the user will know when he may begin typing again. 
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Note: a sudden burst of noise on a telephone line frequently causes INTERLISP 
to receive a rubout, since the code for rubout is 177Q, i.e. all i's. This 
causes INTERLISP to (mistakenly) clear the input buffer and ring a bell. If 
INTERLISP seems to be typing many spurious bells, it is a good indication that 
you have a bad connection. 



2. 
3. 
4. 
5. 



control-0 
control-P 
control-A, Q 
control-R 

control-V 



Miscellaneous 
1 . control-T 



2. controI-S 

3. control-U 



clears teletype output buffer, Sections 2 and 14, 

changes printlevel. Section 14. 

line editing characters, Sections 2 and 14. 1 

causes INTERLISP to retype the input line, useful after 
several control-A's, e.g., 

user types: «-DEFINEQ( ( LAMDA\A\DBA\Acontrol-R 

INTERLISP types: DEFINEQ( ( LAMB 

on input from the terminal, control-V followed by A, B, 
. . . Z inputs the corresponding control character, 
otherwise is a nop. The control-V is not passed to the 
line buffer; the transformation takes place before 
that. Thus ABCtVD followed by two control«A' s erases 
the control-D and the C. ?V takes precedence over , 
i.e. tV inputs a control-C, *VC inputs a C. 



(time) prints total execution time for program. - as well 
as its status, e.g. , 

*-RECLAIM( ) 

GC: 8 

RUNNING AT 15272 USED 0:00:04.4 IN 0:00:39 

1933, 10109 FREE WORDS 

10109 

*• 10 WAIT AT 11623 USED 0:00:05.1 IN 0:00:49 
(storage) change minfs . Section 10. 

if typed in the middle of an expression that is being 
typed to evalqt , breakl or the editor, will cause the 
editor to be called on the expression when it is 
finished being read. See Section 22. 



Control-A, Q, R, and V are not interrupt characters, since their effect 
does not take place when they are typed, but when they are read. Section 
14 describes how these pseudo-interrupt characters can also be disabled 
and/or redefined. Note that control-A, Q, R, and V have their special 
effect only on input from the terminal. On input from files, they are 
treated the same as any other character. 
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MASTER INDEX 



Names of functions are In upper case, followed by their arguments enclosed in 
square brackets [J, e.g. ASSOC[X;Y]. The FNTYP for SUBRs is printed in full; 
for other functions, NL indicates an NLAMBDA function, and a a nospread 
function, e.g. ■ LISTFILES[F JLES] ML" indicates that LISTFILES is an NLAMBDA 
nospread function. Words in upper case not followed by square brackets are 
other INTERLISP words {system parameters, property names, messages, etc.). 
Words and phrases in lower case are not formal INTERLISP words but are 'general 
topic references. 
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EVOCX] 18.21 

(EXAM . x) (edit command) 9.66 

EXEC 21.21,23 

EXEC (prog. asst. command) 21.21; 22.34 

EXIT (transorset command) . Al . 12 

EXPR (function type) 4.3; 8.4*6 

EXPR (property name) 8,7-8; 9.85-86,89, 
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. . . . . 23-, 20.6 

EXPRFLG ( printstructure variable/parameter) ..... 20,5,8 

EXPRP[FN] SUBR 8.1,3-6 

exprs ........... o .... . 4.1 
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FILEFNSLST[FILE] 14.73 
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input buffer 10.18; 14.16,21, 33,35, 
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INT (record field type) 23.57 

integer arithmetic 13.2-6 

INTEGER (record field type) 23.57 

integers 3.5 

interf ork communication 21.18 

interpreter 8.9; 16.1 

INTERRUPT[ INTFN ; INTARGS ; INTYPE ] 10.19; 16.2 

interrupt characters 2.5; 16.16; A3. 2 

INTERRUPTCHAR[ CHAR ; TYP/FORM ; HARDFLG 3 16.17 

INTERRUPTED BEFORE (typed by system) 16.2 

INTERSCOPE 20.10-20 

INTERSECTION X;Y] 6.10 

IN? (break command) 15.8,13; 16.1 

IOFILE[ FILE ] SUBR 14.6-7 

IPLUS[X1 ;X2; . . . ;Xn] SUBR 6 13.3 

IOUOTIENT[X;Y] SUBR . 13.4 

IREMAINDER[X;Y] SUBR . , 13.4 

(IS GLOBAL) (compiler error message) 18.52 
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IS NOT DEFINED (typed by PRINTSTRUCTURE) 
iterative statements (in clisp) ........ 

ITIMES[X1 ;X2; . . . ;Xn] SUBR* 

I . S . TYPE[ NAME ; FORM ;OTHERS] 

i.s. types 

JFN 

OFNSt JFN;AC3] 

0OIN (clisp iterative statement operator) 
JOINC (edit command) ................... 

OSYS .......... 

OS YS[ N ; AC 1 ; AC2 ; AC3 ; RESULTAC ] SUBR* 

keyboard layout . ... 

KFORK[ FORK ] 

KWOTE[X] 

LAMBDA 

LAMBDACOMS (transor command) 

LAMBDASPLST (dwim variable/parameter) .. 

LAMS (compiler variable/parameter) 

LAP . 

LAP macros 

LAP op-defs 

LAP statements 

LAPFLG (compiler variable/parameter) ... 

LAPRDC FN ] .... 

large integers 



LASTtX] ■ ... .' 

LAST (as argument to advise) 

LASTAIL (editor variable/parameter) ... 

LASTGC FILE ] SUBR . 

LASTFN[ FN] . . ... . . ....... 

LASTNt L ;N] .......... 

LASTP05 i (break variable/parameter) .... 

LASTVALUE (property name) 

LASTWORD (dwim variable/parameter) .... 
LASTWORD (system variable/parameter) .. 
LAST- PRINTSTRUCTURE 

( printstructure variable/parameter) 

( LC . (?) (edit command) 

LCASELST (prettydef variable/parameter) 
LCFIL (compiler variable/parameter) 

(LCL . @) (edit command) 

LCONC[PTR;X] 

LDIFF[X;Y;Z] ..... 

LDIFF: NOT A TAIL (error message) 

LEFTBRACKET (syntax class) 

LEFTPAREN (syntax class) 

LENGTH[L] 

LESSP[X;Y] 

(LI n) (edit command) 

LINBUF[ FLG ] SUBR 

line buffer 

LINEDELETE (syntax class) ... .... 

LINELENGTH[N] SUBR . 



line-buffering 
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20 .4 

23.18-31 
13.3 

23.30-31 
23.20,29-31 
14.8-10 
14.10 
23.19 
9.76 

14. 8-10, 37s 21.22 
21.22 
17.22 
21.20,22 
5.3 

4.1-2,5; 8.3,5,7 
A1.17 
17.17-19 
18.5,10 
18.3.35,41-45 
18.37,45 
18.37 
18.42-45 
18.3 
18.27 

3.1,6,12; 5.13, 
13.1-2,11 

6.7 
19.5 7 

9!l6-17,25.84 
14.16 
20.4,8 

6.8 
15.8-10,12 

9.72 

17.14,24-25,29; 23.13 
9.87 

20.5,7-8 

9.30 
14.62 
18.3.5 

9.30 

6.3-4 

6.9 

6.10 
14.25 
14.25 

6.9 
13.8 

9.8,53 
14.35-36 
14.32,35 
14.29,31 

2.3; 3.9; 5.10; 14.37, 
55 

2.5; 14.12-13,16-17, 
32-35 
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line-feed 

line-feed (edita command/parameter) 

linked function calls , 

LIMKEDFMS (system variable/parameter) 

LINKFNS (compiler variable/parameter) 

LISP (prog. asst. command) . 

LISPFN (property name) 

LISPXC LISPXX ; LISPXID ; LISPXXMACROS ; LXSPXXUSERFM ; 
LISPXFLG] o... 



LISPXCOMS (prog. asst. variable/parameter) 

LISPXEVAL[ LISPXFORH ; LISPXID] 

L IS PXF I ND[ HISTORY ; LINE ;TYPE ; BACKUP ;QUIETFLG] . .'. . 
LISPXFINDSPLST (prog. asst. variable/parameter) . 
LISPXHI5T (prog. asst. variable/parameter) ...... 

LISPXHISTORY (prog. asst. variable/parameter) 

LISPXHISTORY (system variable/parameter) 

LISPXHISTORYMACROS 

(prog. asst. variable/parameter) 

LISPXLINE (prog. asst. variable/parameter) 

LISPXMACROS ...... 

LISPXMACROS (prog. asst. variable/parameter) . . 

LISPXPRINT[X;Y;Z;NODOFLG] .. 

LISPXP'RINTFLG (system .variable/parameter) . . 

LISPXREAD[ FILE ;RDTBL] . 



LISPXREADFN (prog. asst. variable/parameter) .... 

LISPXREADP[ FLG ] 

LISPXSTATS[FLG] . . .. 

LISPXUNREAD[ LST] . . 

LISPXUSERFM (prog. asst. variable/parameter ) .... 

LISPXWATCH[STAT;N] . . ., 

LISPX/[X.;FN;VARS] . . . . . . 

LIST[X1 ;X2; . . . ;Xn] SUBR** 

list manipulation and concatenation 

list nodes «..«...«..••««,«...»«• .«.*««.. «.....««««• 

LIST (makefile option ) . . ... 

LIST (property name) 

LISTFILESC FILES ] NL* ' 

LISTFILESTR (file package variable/parameter) 

LiSTFILESIC FILES] 

LISTING? (compiler question) . 

L1STP[X] SUBR ...... . . 

listp checks (in pattern match compiler) • 

lists 

LISTS FULL (error message) 

LITATOM[ X ] SUBR 

literal atoms 



LITS (edita command/parameter) 

LLSH[N;M] SUBR 

( LO n) (edit command) ....... 

LOAD[ FILE ; LOFLG ; PRINTFLG] . . . 
LOADAV[ ] 



3.2; 14.11,19 
21.13 
18.23-28 
18.27 

18.26,31-32 
21.21; 22.34 
23.74 

9.62,73; 17.5,12-14.29, 

22.10-11,15,17,19,21, 
29,34-35,37-38, 
40-41,44-47,47-49, 
52,62 

22.38 

22.52 

22.53,62 

22.14 

22.45-46.56,59-60 

22.44,49,60,62 

22.62 

22.34 

22.34 

21.21 

22.34,49 

22.37,45 

22.38 

22.10, 19,29,32,47-48,50, 

61 

14.17; 22.50 
22.50,61 
22.63,65 
22.51 

22.35,37.47,49 

22.63 

22.40,58 

3.8; 6.1 

6.1-12 

3.9,12 
14.68 

8.7 

14.66,68.71 
14.72 
14.72 
18.2-3 

2.3; 5.13 
23.40 

2.3; 3.1,8; 5.13 
16.10 

5.12 

3.2.4; 5.12; 10.11, 
14.12 
21.13 
13.5 

9.8.53 

2.9; 14.39; 18.9 

21.22 
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LOADBLOCK[ FN ; FILE ; LDFLG ] 14.42 

LOADEDFILELST (file package variable/parameter) • 14.64 

LOAOFNSC FNS ; FILE ; LDFLG ;VARS] 14.40 

LOADFROM[ FILE ;FNS ; LDFLG] . 14.41; 18.14 

LOADVARSC VARS ; F ILE ; LDFLG ] 14.41 

LOC[X] SUBR . 13.13-14 

local record declarations (in clisp) 23.37 

local variables . 5.6 

LOCALFREEVARS (compiler variable/parameter) 18.20-21,31 

locally bound variables 12.7 

location specification (in editor) * 9.28-29,64 

LOCATION UNCERTAIN (typed by editor) 9.17 

LOG[X] 13.9 

LOGAND[ XI ;X2; . . . ;Xn] SUBR* 13.5 

LOGOR[Xl;X2;...;Xn] SUBR^ ..... 13.5 

LOGOUT[ ] SUBR ........ ...,o 2.4; 21. 5, 21 

LOGXOR[ XI ; X2 ; . . . ; Xn ] SUBR* . . . . 13. 5 

LOOKAT[ FNL] . .. 20.12,16 

lower case 14.62 

lower case comments . 14.59-62 

lower case input . . 14 .32 

(LOWER x) (edit command) .. .. 9.75 

LOWER (edit command) ............................ 9.74 

LOWERCASE! FLG ] .. . 23.81 

(.LP . corns) (edit command) 9.65-66 

( LPQ . corns ) ( edit command) 9 .66 

LRSH[ N ;M 3 . . . . . 13.6 

LSH[N ; M 3 SUBR . . . ......... . . ..... 13.5 

LSTFIL (compiler variable/parameter) 18.3 

LSUBSTC X ; Y ; Z 3 ......... 6.6-7 

L-CASE[X;FLG3 . 9.74; 14.62 

(M c . corns) (edit command) .. 9.67 

(M (c) arg . corns) , 9.68 

(M (c) (argl ... argn) . corns) (edit command) ... 9.68 

machine instructions 18.1,41-45;' 21 .10 

MACRO (property name) . . . 18. 15-16 

MACRO ( type of re^d macro) 14.26 

macros (in compiler) 0 . 18.16-17 

macros (in editor) .......... 9.67-70 

MAKEBITTABLE[L;NEG;A3 10. 10 

MAKEFILE[ FILE ; OPTIONS ; RE PRINTFNS;SOURCEF ILE] 14.66,68,72; 17.29, 

18.14 

makefile and clisp 23.35,79 

MAKEF I LE REMAKE FLG 

(file package variable/parameter) .......... 14.68 

MAKEFILES[ OPTIONS ; FILES 3 14.71,75 

MAKESYS[ F ILE 3 EXPR . . . . . . 3.16 

MAKESYSDATE (system variable/parameter) . 3.16 

MAKEUSERNAMES .......... ... . 22.66 

MAP[ MAPX ; MAPFN 1 ;MAPFN2 3 11.2 

MAPATOMS[FN3 SUBR ............... 10.5 

MAPC[MAPX ;MAPFN1 ;MAPFN2 3 . . . « . . . . . . 11.3 

MAPCAR[ MAPX ; MAPFN1 ;MAPFN2 3 11.3 

MAPCON[ MAPX ;MAPFN1 ;MAPFN2 3 ... 11.3 

MAPC0NC[MAPX;MAPFN1;MAPFN23 ... .............. 11.3 

MAPDL[MAPDLFN;MAPDLPOS] ... 12.11 

MAPHASH[ ARRAY ; MAPHFN ] 7.6 
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MAPLIST[MAPX;MAPFM1 ;MAPFN2] . 11.3 

MAPRINT[ LST ; FILE ; LEFT ; RIGHT; SEP; PFN; LSPXPRNTFLG]. . 11.5 

MAP2C[MAPX;MAPY;MAPFN1 ;MAPFN2] 11 .4 

MAP2CAR[ MAPX ; HAP Y ; MAPFN 1 ;MAPFM2 ] 11.4 

margins ( for pre ttyprint) 14.54 

(HARK atom) (edit command) 9.34 

HARK (edit command) 9.34 

MARKLST (editor variable/parameter) 9,34,34 

MASK (edita command/parameter) . ... 21.15 

HATCH (use in pattern match in clisp) 23.39 

HAXLEVEL (editor variable/parameter) 9.24,28 

HAXLOOP EXCEEDED (typed by editor) 9.66 

MAXLOOP (editor variable/parameter) 9.66 

(MBD el ... em) (edit command) , 9,47 

MEMB[ X ; Y] 5.16 

MEMBER[X;Y] 5.16 

MERGE[ A;B ;COMPAREFM] 6.11 

MINFS[ N ; TYP ] SUBR . 3.14-15; 10.17 

MINUS[X] SUBR 13.6 

MINUSP[X] SUBR . 13.4,7 

MISSING OPERAND (dwim error message) 23.68 

MISSING OPERATOR (dwim error message) 23.68 

MISSPELLED ?[ XWORD ;REL;$PLST;FL(j ; TAIL ; FN ] 17,25,29 

mixed arithmetic 13.7-8 

MKATOM[ X ] SUBR 3.2-3,6-7; 10.8 

MKSTRING[ X] SUBR 3.11-12; 10.6,12 

MKSWAP[ X ] 3.21 

MKSWAPP[ NM ; DF ] .. 3,21 

MKSWAPSIZE (Overlay variable/parameter) ......... 3.22 

HKUNSWAPC X] 3.21 

MODEL33FLG (dwim variable/parameter) 17,22 

MOVD[FROM;TO;COPYFL6J ...... .... * 8.4 

(MOVE 91 TO com . @2) (edit command) 9,48-51 

(MULTIPLY DEFINED TAG) (compiler error message) . 18.51 
(MULTIPLY DEFINED TAG, ASSEMBLE) 

(compiler error message) 18.51 

(MULTIPLY DEFINED TAG, LAP) 

(compiler error message) 18.51 

(N el ... em) (edit command) 9.36 

(n el ... em) (n a number, edit command) ........ 9.5,36 

n (n a number 9 edit command) 9.3,17 

(n) (n a number, edit command) 9.5,36 

NAME (prog. asst. command) 22.14,22,26-27 

NAMES RESTORED (typed by system) . 15.25 

NAMESCHANGED (property name) 15.19 

NARGS[ X 3 8.1,3-4,6 

NCHARS[X;FLG;RDTBL3 SUBR 10.3; 14.7 

?iCONC[Xl;X2;...;Xn] SUBR* 6.2-3 

NCONCl[LST;X3 6.2-3 

NEQ[X;Y3 5.13 

NEVER (clisp iterative statement operator) 23.20 

NEW (makefile option) 14.68 

NEWFILE2C NAME ;COMS ; TYPE ;UPDATEFLG] 14 . 73, 75 

NEWFILE ?[ NAME ; CHANGEDLST ] 14.76 

NEW/FN[ FN 3 .. 22.58 

(NEX x) (edit command) 9.32 

N'EX (edit command) .... 9.32 
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NIL ....... ....... v. ............ ........ ......... 2.2 

NIL (edit command) 9,64,70 

NIL (use in block declarations) 18.32 

NIL: 20.5 

NLAM ( transor command) . Al .15 

NLAMA (compiler variable/parameter) 18.5 

NLAMBDA ........ 4.1-2 P 5; 8.3,5 

NLAML (compiler variable/parameter) 18.5 

NLEFT[ L ; N ; TAIL ] 6.8 

NLISTP[X] .. ... 2.2; 5.13 

NLISTPCOMS (transor command) Al .16 

NLSETQC NLSETX] NIL 5.8; 16.15-16; 18.18, 

. . 22 . 59 

(NO BREAK INFORMATION SAVED) *.*.!!•!!!!!•!!!!!!!!! 15^24 
(NO LONGER INTERPRETED AS FUNCTIONAL ARGUMENT) 

(compiler error message) 18.50 

NO propname PROPERTY FOR atom (error message) ... 14.49 

NO VALUE SAVED: (error message) 22.56 

NOBIND .... 2.3,9; 3.4; 5.9; 9.87, 

. 14.39; 16.1; 22.43,55 

NOBREAKS (break variable/parameter) 15.22 

NOCLISP (makefile option) 14.67; 23.35,80 

NOFIXFNSLST (clisp variable/parameter) 23.66-67,76 

NOFIXVARSLST ( clisp variable/parameter ) .. 23.66-67,69,76 

NOFNS ( printstructure variable/parameter) 20.3 

NOLI NKDEF 18.26-27 

NOLINKFNS (compiler variable/parameter) 18.26-27,31-32 

( NON ATOMIC CAR OF FORM) (compiler error message). 18.50 

NONE (syntax class) 14.30 

NONXMEM (error message) .. . 16,7 

NON-NUMERIC ARG (error message) 13.2,6-7; 16.4,8 

NORAISE ( TENEX command) 14.32 

NOSAVE . . . . 22.56-57 

NOSPELLFLG ( clisp variable /parameter ) 23.76 

nospread functions ............................. . 4.2; 8.1 

NOSWAPFNS (Overlay variable/parameter) .......... 3.22 

NOT[X] SUBR ..... . 5.13 

NOT A FUNCTION (error message) 8.8; 19.6 

NOT BLOCKED (typed by editor) 9.79 

(NOT BROKEN) .. 15.24 

NOT CHANGED, SO NOT UNSAVED (typed by editor) ... 9.85 

(NOT COM PILE ABLE ) (compiler error message) ...... 18.8,52 

NOT COMPILEABLE (compiler error message) 18,52 

NOT DUMPED (error message) 14.71 

NOT EDITABLE (error message) 9.83,86 

NOT FOUND (compiler error message) 18.53 

NOT FOUND (error message) 14,72; 18.13 

(NOT FOUND) (typed by break) 15.9 

(NOT FOUND) (typed by breakin) 15.21,23 

(NOT FOUND) (value of unsavedef) ................ 8.8 

NOT FOUND, SO IT WILL BE WRITTEN ANEW 

(error message) ...... . ................. 14.69 

(NOT IN FILE - USING DEFINITION IN CORE) 

(compiler error message) ................... 18.53 

NOT ON BLKFNS (compiler error message) 18.22,29,53 

(NOT PRINTABLE) ... .... 14.46 

NOT AN Y[ SOME X; SOME FN 1 ;SOMEFN2] . . ........ ; 5.16 
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NOTCOMPI LEDF JLES (file package variable/parameter) 14.66-67,72 

MOTE (transor command) . Al.12,14 

NOTEVERY[EVERYX;EVERYFNl ;EVERYFN2] 5.16 

NOTE: BRKEXP NOT CHANGED, (typed by break) 15.12 

( NOTHING FOUND) 8.8 

NOTHING SAVED (typed by editor) 9.78 

NOTHING SAVED (typed by system) 22.23 p 39 

NOTLISTEDFILES (file package variable/parameter).. 14.66-67,71-72 

MOTRACEFNS ( printstructure variable/parameter ) 20.4 

MOT-FOUND : 14.41 

NP (in an assemble statement) 18.47 

NTH[ X;N] 6.8 

(NTH n) (n a number, edit command) 9.20 

(NTH x) (edit command) 9.32-33 

NTHCHAR[ X;N ;FL6;RDTBL] SUBR* 10.4 

NTYP[X] SUBR . 10.15 

NULL[X] SUBR 5.13 

null string 10.6-7 

null-check 2.2; 6.7-10 

number stack ....... . . .... 12.3; 18.47 

NUMBERP[X] SUBR . . . 5.12 

numbers 5.12; 13.1-14, 

14.12-13 

(NX n) (n a number , edit command) , 9.19 

NX (edit command) .... .. 9.8,18-19 

OCCURRENCES (typed by editor) 9.65 

octal 3.6,9; 14,12,19 

OK TO REEVALUATE (typed by dwim) 17.9 

OK (break command) 15.6-7,12,15,17, 

♦ • ....... 16.3-4 

OK (edit command) 9.71,76,83 

OK (edita command/parameter) 21.13 

OKREEVALST (dwim variable/parameter) V. 17.9 

OLD (clisp iterative statement operator) 23.8,21-22 

ON (clisp iterative statement operator) 23.22,24 

OPCODE (in a lap statement) , 18.42 

(OPCODE? - ASSEMBLE) (compiler error message) ... 18.37,52 

OPD (property name) 18.37,42,45; 21.10-11 

open functions 18.14-15 

open macros 18.16 

OPENF[FILE;X] SUBR 14.8 

opening f lies 14. 1 

OPEMP[ F ILE ; TYPE ] SUBR 14.3,5,8 

OPENR[A] SUBR 10.19 

OPNJFN[ FILE ] SUBR 14.9 

OR[Xl;X2;...;Xn] FSUBR® . 5.14 

order of precedence of CLISP operators 23.15 

(ORF ...) (edit command) 9.27 

ORG (edita command/parameter) 21.12 

ORIG (used as a readtable) 14.22 

(ORR ...) (edit command) 9.66 

OTHER (syntax class) .............. 14.23 

OUTFILE[ FILE ] SUBR 14.2,6-7 

OUTFILEPC FILE ] SUBR ..... 14.3-4 

OUTPUT[FILE] SUBR 5.10; 14.1 

output buffer . . 14.21 

OUTPUT FILE: (compiler question) 18.2,5 
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output functions 

overflow . 

overlays 

(P m n) (edit command) 

(P m) (edit command) 

P (edit command) 

P (prettydef command) 

PACK[X] SUBR . .. 

PACKCCX] SUBR 

page 

PAGEFAULTSU • 

parameter pushdown list 

parentheses counting (by READ) 

PARENTHESIS ERROR (error message) 

PATHSt X ; Y ; R ; MUST ; AVOID ;ONLY] 

PATLISTPCHECK (in pattern match compiler) 

pattern match compiler 

pattern match (in editor) 

(pattern .. @) (edit command) .......... 

PATVARDEFAULT (in pattern match compiler) 

PEEKC[FILE] SUBR ... ....... 

place-markers (in pattern match compiler) 

PLUS[X1 ;X2; . . . ;Xn] SUBR* 

pname cell 

pnames 



pointer 

POINTER (record field type) 

POSITION[FILE] SUBR 

PP[X] ML* 

PP (edit command) 

PPT[X] ML* 

PPT (edit command) . . 

PPV (edit command) 

PP*[X] ML* 

PP* ( edit command) ..... 

PRDEPTH ( printstructure variable/parameter) 

precedence rules (for CLISP operators) .......... 

predicates 

prefix operators (in clisp) .... 

PRESCAN[ FILE ;CHARLST] 

PRETTYCOMSPLST (prettydef variable/parameter) ... 
PRETTYDEF[ PRTTYFHS ; PRTTYFILE ; PRTTYCOMS ;REPRINTFNS ; 

SOURCEFILE ; CHANGES] 



prettydef commands 

PRETTYDEFHACROS (prettydef variable/parameter) .. 

PRETTYFLG (prettydef variable/parameter) 

PRETTYHEADER 

PRETTYLCOM (prettydef variable/parameter) 

PRETTYPRINT[ FNS ; PRETTYDEFLG] 

PRETTYPRINTMACROS (prettydef variable/parameter).. 

PRETTYTABFLG (prettydef variable/parameter) 

PRETTYTRANFLG (clisp variable/parameter) 

PRETTYTYPE (property name) 

PRETTYTYPELST (file package variable/parameter) . 
primary input file 
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14.19-21 
13.3.6 

3.17-22 

9.60 

9.60 

9.2,60 
14.50 

3.2-3,6-7,12; 10.2 
10.4 

3.12 
21.4 

12.3,9,11; 18.47 
14.12,33 

5.3 
20!l3-14 
23.40 
23.38-49 

9.21-23,89-90 

9.33 
23!41,44,47 
14.16,35 
23.46 
13.7 

3.4 

3.1-2,4-5,12; 10.1-5, 
11 

3.1 
23.57 
14.37 

14.45; 18.47 

9.2,60 
23.33,80 

9.61; 23.33,80 

9.61; 14.55 
14.47 

9.61 
20.4 
23.10 

2.3; 5.13 
23.13 
A1.3 
14.53 

2.9; 5.9; 14.47-55,57, 
63,66; 19.9 
14.49-53 
14.52,57,73-74 
14.57,6? 
14.54 
14.56-57 

2.9; 14.45 
14,58 
14.45 

14.67; 23.33-34,79 

14.74 

14.75 

14.1-2,4,11 
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primary output file 

primary readtable 

primary terminal table 

PRINT[X;FILE] SUBR 

print name 

PRINTDATE[ PRTTYFILE ;CHANGES] 

PRINTDEF[EXPR; LEFT ;DEF ;PRETTYDEFLG ] 

PRINTFfJS[X] 

PR I NTH IS TOR Y[ HISTORY ; LINE ;SKIPFN ;NOVALUES ] 

printing circular lists 

printlevel 

PRINTLEVEL[N] SUBR 

PRINTSTRUCTURE[ X ; EXPRFLG ;FILE] 

PRIN1[X;FILE] SUBR 

PRIN2[X;FILE] SUBR . 

prin2-pnames 

private pages 

PROG[ARGS;El ;E2; . . . ;En] FSUBR a 

PROG label 

PROGN[Xl;X2; . . . ;Xn] FSUBR« 

programmer's assistant 

programmer's assistant and the editor ... 

programmer's assistant commands 

PR0G1[X1;X2; . . . ;Xn] FSUBR* 

prompt character 



PROMPTCHAR[ID;FLG;HIST] 

PROMPT»FLG (prog. asst. variable/parameter) 

PROP[X;Y] 

PROP (prettydef command) 

PROP (typed by editor) . . . 

proper tail 

property . . 

property list ... 

property name 

property value 

PROPRECORD (record package) 

pseudo-carriage return 

PSTEP (in an assemble statement) 

PSTEPN (in an assemble statement) 

pushdown list 

pushdown list functions 

PUT[ ATM ; PROP ; VAL ] . 

PUT0[X;Y] SUBR 

PUTDQ[X;Y] ML .... 

PUTHASH[ ITEM; VAL; ARRAY] SUBR 

PUTL[LST;PROP;VAL] 

P-STACK OVERFLOW (error message) 

P.P.E. (typed by PRIHTSTRUCTURE) 

0 (following a number) 

QUIT (tenex command) 

QUOTE[X] ML* 

QUOTIENT[X;Y] SUBR . 

(R x y) (edit command) 

R (edit command) 

RADIX[N] SUBR 



14.1.4,19 

14.11,19,22,29 

14.28-29 

3.2,9,11; 14.20 
10.1 
14.54 

14.54-55,57 
14.54 

22.23,37-38,60 

21.23-29 

14.20-21 

2.3; 3.9; 5.10; 14.20 
20.1-9 

3.2,9,11; 14.19-20 

3.2,9,11; 14.19-20 
10.1-4 

3.16 

5.6 

5.7 

4!4; 5.6 
22.1-48 
22.61 
22.10-31 

5.6 

2.4,6,8; 9.2; 15.4, 
22.10,33.51 
22.33,51,61 
22.33,51 

8.7 

14.49,52 
9.85 
5.16 
7.1 

2.3; 3.4; 7.1-4; 16.1 

7.1,4 

7.1,4 
23.55 
22.18 
18.47 
18.47 

2.8; 4.2; 12.1-13 
12.7-11 
7.1-2 

2.3,8; 8.1-4 

8.4 

7.6 

7.1; 23.55 
16.7 
20.4,7 

3.6; 14.12.19,36 
14.71-72; 21.19-21 

5.3 
13.8 

9.7,57 

6.6 

2.3; 3.6; 5.10; 14.12, 
19,36 
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RAISE[ MODE ; TTBL ] SUBR . 14.32 

(RAISE X) (edit command) . .................. 9.75 

RAISE (edit command) 9.74 

RAISE (TENEX command) ... 14.32 

RAND[ LOWER ; UPPER] . . 13.10 

random numbers 13. 10 

RANDSET[ X] 13.10 

RANDSTATE 13.10 

RATEST[ X] SUBR 14.15 

RATOM[FILE;RDTBL] SUBR .. 14 .12-14,34 

R ATOMS[ A ; F I LE ; RDTB L ] 14.13 

(RC x y) (edit command) 9.59 

RC (makefile option) 14.67 

(RC1 x y) (edit command) 9.59 

READ[FILE;RDTBL;FLG] SUBR 14.11-12,34 

read macro characters 14.24,26-27 

READBUF (prog. asst. variable/parameter) ........ 22.50-51 

READC[ FILE] SUBR 14.15,35 

READFILE[ FILE] 14.39 

reading from strings 14.11 

READLINE[ RDTB L ; LINE ;LISPXFL6] 9.81; 14.17-18; 22.14, 

..." 19,32,37,47-48,50,6! 

READMACROS[ FLG ;RDTBL] SUBR 14.27 

READP[FILE;FLG] SUBR 14.16 

READTABLEP[ ROTBL] SUBR 14.22 

readtables 14.11,19,21-27 

READVICE (property name) 19.8-10 

READVISECX] NIL* 14.51? 19.8-9 

READ-MACRO CONTEXT ERROR (error message) . . 14.27; 16.11 

REAL (record field type) ., «. 23.57 

REBREAK[ X] NIL* 15.18,24 

RECLAIM[ N ] SUBR 3.13-14; 10.15 

RECOMPILE[ PFILE ;CFILE ;FNS] 14.67,72; 18.7-8,11, 

. 11-14,32 

reconstruction (in pattern match compiler) 23.47 

record declarations (in clisp) 23.37,53-59 

record package (in clisp) ....... 23.50-62 

RECORD (record package) . 23.55 

RECORDS (prettydef macro) 23.53-54 

(REDEFINED) (typed by system) 14.39 

REDEFINED (typed by system) 8,7 

REDEFINE? (compiler question) 18.4 

REDO N TIMES (prog. asst. command) .... 22.14 

REDO (prog. asst. command) 22.14,18,22 

REENTER (tenex command) . 2.4,10; 5.9; 21.5,19 

REHASH[ OLDAR ; NEWAR ] SUBR 7.6 

RE LBLK[ ADDRESS ; N ] SUBR 16.10; 21.18 

RELINK[ FN ;UNLINKFL6] 18.27-28 

relinking 18,27-28 

relocation information (in arrays) .............. 3.9 

REHAINDER[ X ; Y ] SUBR .................... . .. 13.8 

REMAKE (makefile option) 14.68 

REMARK (transor command) Al . 12 

REMOVE[X;L] 6.4 

REMPROP[ATM;PROP] 7.2 

REPACK (edit command) 9.75 

(REPACK (s») (edit command) 9.76 
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REPEATUNTIL (clisp iterative statement operator).. 23.23 

REPEATWHILE (clisp iterative statement operator).. 23.23 

REPLACE (use in records 1n clisp) 23.61 

(REPLACE @ WITH . ..) (edit command) 9.42 

replacements (in pattern match compiler) 23.46 

REREADFLG (prog. asst. variable/parameter) 22.50,52 

RE5ET[ ] SLfBR 16.15 

RESET (typed by system) 22,43,55 

RESETFORM[ RESETX ; RESETY ; RESETZ ] WL 5.10 

RESETLST[ RESETX] WL* 5.11 

RESETREADTABLE[ ROTBL ;FROM] SUBR 14.23 

RESETSAVE[ RESETX] WL* 5.11 

RESET TERMTABLE[ TT8L ;FROM ] SUBR 14.29 

RESETVAR[ RESETX; RESETY; RESETZ ] WL 5.9; 9.77; 18.7 

(RESETVAR var form , corns) (edit command) 9.77 

restoring input buffers 22.30 

RESULTS[ ] 21.5,8 

RETEVAL[ POS ;FORM] SUBR . . . . 12.10; 15.5; 17.15 

RETFNS (compiler variable/parameter) 18.21,28,31 

RETFROM[ POS ; VALUE ] SUBR 12.10; 15.5; 16.6 

RETRIEVE (prog. asst. command) 22.22,26,34 

RETRY (prog. asst. command) • 22,22 

RETURN[ X] SUBR . ...... 5.7 

RETURN (break command) 2.9; 15,6-7,175 16.1, 

4 

RETURN (use in iterative statement 1n clisp) .... 23.27 

RETYPE (syntax class) 14.29 

REUSING (record package) 23.60 

REVERSE[ L ] ...... . . . . .... 6 .5 

REVERT (break command) .. ... . 15.14 

(RI n m) (edit command) 9.8,53 

RIGHTBRACKET (syntax class) 14.25 

RIGHTPAREN (syntax class) 14.25 

RLJFN[ OFN 3 14.10 

(RO n) (edit command) ........................... 9.8,53 

root name of the file 14.64 

RPAQ[ RPAQX ; RPAQY] WL 5.9; 14.39,48; 22.43 

RPAQ0[X;Y3 WL 5.9; 14.39,48-49, 

22.43 

RPLACA[X;Y3 SUBR 5.3 

RPLACD[X;Y3 SUBR 5.2 

RPLNODE2[ X; Y3 22.57 

RPLSTRING[X;N;Y3 SUBR 10.7,12; 16.10 

RPT[ RPTN ; RPTF 3 8.10-11 

RPTQ[ RPTN ;RPTF3 WL 8.11 

RSH[N;M3 13.5 

RSTRING[ FILE ;RDTBL3 SUBR 10.6; 14.13 

rubout 2.5; 14.33; A3. 1 

RUN (tenex command) 3.16 

running other subsystems from within 1NTERL1SP .. 21.19 

RUNONFLG (dwim variable/parameter) 17.26 

run-on spelling corrections 17.5,26 

(Rl x y) (edit command) 9.59 

(S var . 0) (edit command) 9.36 

S (response to compiler question) 18.4 

S ASSOC [ XSAS ; YSAS 3 5.17 

SAVE EXPRS? (compiler question) 18.4 
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SAVE (edit command) .......... 9.72,74,83-84 

SAVE0EF[X] 8.7-8 

SAVESET[ NAME ;VALUE ;TOPFLG;FLG] ......... 22.40,43,55 

saving unusual data structures 21.28 

search algorithm (in editor) 9.23-25 

searching files . . 14.7 

searching strings 10.8-11 

searching the pushdown list 12.7,9-11 

SEARCHING . . . (typed by breakln) 15.22 

SEARCHPDL[SRCHFN;SRCHPOS] 12.11 

second pass (of the compiler) ........ 18.35 

segment patterns (in pattern match compiler) .... 23.43-45 

SELECTOC X; Yl ; Y2 ; . . . ;Yn ;Z] Nl* 5.4-5 

separator characters 14.13-16,25,34 

SEPR (syntax class) . 14.23,25-26 

SEPRCHAR (syntax class) . . . 14.25 

SET[X;Y] SUBR 5.8 

SETA[A;N;V] . 3.9; 10.14; 16.10 

SETARG[ VAR ;M ; X] FSUBR 8.12 

SETBRK[LST;FLG;RDTBL] SUBR 14.13-14 

SETD[A;N;V] 3.9; 10.15 

SETFN (property name) 23.74 

SETN[VAR;X] ML 13.10-13 

SETQC X ; Y] FSUBR* 5.8 

SETO (in an assemble statement) ................. 18.40 

SETQOC XSET;YSET] ML : 5.8 

SETREADTABLE[ RDTBL;FLG] SUBR ... 14.23 

SETSBSIZE[N] SUBR ...... 3.22; 16.11 

SETSEPR[LST;FLG;RDTBL3 SUBR 14.13-14 

SETSYNTAX[ CH ;CLASS ;TABLE] ........... 14.24 

SETTERMTABLE[ TTBL] SUBR . . 14.28 

SFPTR[ FILE ; ADDRESS] SUBR 14.7,37; 16.10 

SHALL I LOAD ( typed by dwim) 17.18 

shared pages 3.16 

shared system 3.16 

sharing .... . 3.16 

SHOW (transorset command) ALIO 

(SHOW . x) (edit command) .... 9.66 

SIDE (property name) 22.45-46,56-57,59,61 

SIN[ X ; RADIANSFLG ] 13.9 

skip-blip 12.11 

SKOR 17.21-23 

SKREAD[ FILE ; REREADSTRING] 14.18-19 

slot (on pushdown list) 12.2,10 

small integers 3.1,6; 5.13; 13.1-2 

SMALLP[N] 3.6; 13.2.4 

SNDHSG (prog. asst. command) 21.21; 22.34 

SOME[SOMEX;SOMEFN1;SOMEFN2] 5.15 

SORT[ DATA ;COMPAREFN] 6.10 

SP (in an assemble statement) 18.40,47 

space 3.2 

SPACES[N;FILE] SUBR 14.20 

SPEGVARS (compiler variable/parameter) 18.20,28,31 

spelling completion 17.il 

spelling correction 9.80,82,86-87, 

14.52-53; 15.16; 22.14, 

• 38; 23.11,17,19,75 



INDEX. 26 



Page 
Numbers 



spelling correction protocol 17.5-7 

spelling corrector 17.2,10-12,20-23,28 

spelling list ... 15.16 

spelling lists 9.80,82,86; 14.52-53, 

. 17.12-15,17-19; 22.14, 

38; 23.11,17,19,75 

SPELLINGS1 (dwim variable/parameter) 17.12-14,19,24 

SPELLINGS2 (dwim variable/parameter) 17.13-14,18-19,24 

SPELLINGS3 (dwim variable/parameter) 17.13-14,17,24; 22.55 

SPLICE (type of read macro) 14.26 

(SPLITC x) (edit command) 9.77 

spread functions 4.2; 8.1 

spreading arguments 4.2 

S0RT[N] . .. 13.9 

SORT OF NEGATIVE VALUE (error message) 13.9 

square brackets , 2.6 

square brackets (inserted by prettyprint) 14.55 

SRCCOM 6,12 

ST (response to compiler question) 18.2,4 

STACK OVERFLOW IN GC - COMPUTATION LOST 

(error message) 16.8 

stack position 12.7-10 

statistics 22.63 

STF (response to compiler question) 18.4 

STKARG[N;POS] SUBR 15.9 

STKARGNAMEC M ; POS] . 12.9 

STKARGS[ POS] 12.9 

STKARGVAL[ U ; POS ] 12.8 

STKEVAL[POS;FORH] SUBR ......... ..... .... 12.10-11; 15.9 

SiXNAMEC POS] SUBR 12.8 

STKNARGS[POS] SUBR . 12.8 

STKNTH[N;POS] SUBR 12.8-9 

STKPOS[FN;N;POS] 12.7-9 

STKSCAN[VAR;POSi SUBR 12.10 

STOP (at the end of a file) 14.39,44,54 

STOP (edit command) 9.71-72,76,83-85, 

, . . . 15.21 

storagec flg y .................. .. . . . . . . . . . . . . . . . ! 10 ! is 

storage allocation 3.12 

STREQUAL[X;Y] .... 10.6 

STRF (compiler variable/parameter) 18.3-4,8 

string characters 3.1,11-12; 10.11 

string functions 10.5-11 

string pointers 3.1,11-12; 10.7,11 

string storage 10.11-12 

STRINGDELIM (syntax class) 14.25 

STRINGPC-X] SUBR 5.13; 10,5 

strings 3.11; 5.13; 14.12 

STRPOS[X;Y;START;SKXP;ANCHOR;TAIL] 10.8-9; 14,7 

STRPOSL[ A ;STR ; START ;NE6] 10.10 

structure modification commands (in editor) 9.36-60 

SUBLIS[ALST;EXPR;FLG] ... 6.6-7 

SUBPAIR[OLD;NEW;EXPR;FLG] 6.7 

SUBR (function type) 4.3; 8.4-6 

SUBR (property name) 8.7-8 

SUBRPCFN] SUBR 8.1,3-5 

subrs 8.1 
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SUBR* (function type) 4.3; 8.4-6 

SUBSET[MAPX;MAPFN1;MAPFN2] 11.4 

SUBST[X;Y;Z] 6.5,7 

substitution macros . . 18.17 

SUBSTRING[X;N;M] SUBR 3.11; 10.6,12 

SUBSYS[ F ILE /FORK ; INCOMFILE ;OUTCOMFILE ; 

ENTRYPOINTFLG] 14.71; 21.19-22; 22.34 

SUB1[X] 13.3 

SUCHTHAT (in event address) 22.12 

SUM (clisp iterative statement operator) ........ 23.20 

(SURROUND e IN ...) (edit command) 9.48 

SVFLG (compiler variable/parameter) 18.3-4 

(5W n m) (edit command) 9.59-60 

SWAPBLOCK TOO BIG FOR BUFFER (error message) .... 16.11 

swappable array 3.18 

swapping buffer .. ... . ... 3.18 

SWPARRAY[N;P;V] SUBR 3.20-21; 10.13 

SWPARRAYP[X] SUBR 3.21; 10.14 

SY (prog. asst. command) 22.34 

symbolic file input 14.39-44 

symbolic file output 14.44-55 

SYMLST (edita command/parameter) 21.14-15 

synonyms .. 17.11 

syntax classes . 14.23-30 

SYNTAXP[CH;CLASS; TABLE] 14.25 

SYSBUFt FLG ] SUBR 14.35-36 

SYSHASHARRAY (system variable/parameter) ........ 7.6,8 

SYSIN[ FILE ] SUBR ........ ...... 2.10; 14,38 

SYSLINKEDFNS (system variable/parameter) ........ 18.28 

SYSOUT[ F I LE ] EXPR 2.10; 14 .37-38 

SYSOUTDATE (system variable/parameter) 14.38 

SYSPROPS (system variable/parameter) 7.4; 14.50 

SYSTAT ................................. 21 . 23 

T FIXED ( typed by # dwim) " ! [ ! ! ! ! ! ! ! ! ! !!!!!! .* \ \ \ Y.\\ 17 1& 

TAB[ POS ; M INSPACES ;FILE] 14 . 54 

tab (edita command/parameter) 21.12 

tail of a list . 5.16 

TAILP[X;Y] ... 5.16 

TAN[ X jRADIANSFLG] 13.9 

TCOMPL[FILES] 14.67; 18.7-11,32-33 

TCONC[PTR;X] 6.2-4 

TECO (prog. asst. command) , 21.21; 22.34 

TELNET .. ... 21.30 

TENEX[ STR ] . 21.23 

TEN EX ........................................... 2.4,6,9—10; 3.2,7,16, 

.. 13.13; 14.2-3.7-9, 

....... 20.5; 21 .19,22 

terminal 9.61; 14.1,4,11-12,17, 

32,47 

terminal initiated breaks 16.2-3 

terminal syntax classes 14.29 

terminal tables 14 .28-35 

TERMTABLEP[ TTBL] SUBR 14.28 

TERPRI[ FILE] SUBR 14.20 

TEST (edit command) 9.79 

TEST (transorset command) Ai .11 

TESTMODE[ FLG] 22.41 
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TESTHODEFLG (prog. asst. variable/parameter) .... 22.41 

THERE IS (clisp iterative statement operator) .... 23.20 

THRU (edit command) . 9.54-57 

THRU (in event specification) 22.13 

TIME[ TIMEX ; TIHEN ; TIMET YP] ML 21,1-2 

TIMES[X1 ;X2 ; . . . ;Xn] SUBR* 13.8 

time-slice (of history list) 22.8,54 

TO (clisp iterative statement operator) 23.23-25 

TO (edit command) 9.54-5? 

TO (in event specification) ..... 22.13 

too few arguments . 4.4 

too many arguments , 4.4 

TOO MANY FILES OPEN (error message) 16.9 

TOO MANY USER INTERRUPT CHARACTERS (error message) 16.12 

top level value 5.1,3,9 

TOP (as argument to advise) 19.5,7 

TRACE[ X] NIL* 15.1,7,15,20,23 

translation notes- • Al .4-7 

translations (in clisp) ........ 23.31-35 

TRANSOR[ SOURCEFILE ] . , . Al.3-4 

TRAMSOR 0 .■ Ai.1-17 

transor sweep - A1.14 

TRANSORFNS A1.4 

TRANSORFORM . Al .4 

TRANSORSET[] ... Al.2,8 

TRAPCOUNT[X] SUBR . .. 18.21 

TREAT AS CLISP ? (typed by dwim) 23.69 

TREATASCLXSPFL6. (clisp variable/parameter) ■ 23.69 

TREELST (printstructure variable/parameter) 20.7 

TREEPATHS[ X ; Y ; R ; MUST ; AVOID ; ONLY] 20.15 

TREEPRINT[X;N] ............... 20.8 

true ...«.«••».., «....••••••«.«•••»•»...• 2.2*5.4 

trusting ' ( dwim * mode )"!!!!!!!!! .° !!!!!!!!!!!!!!!!! ! i7!3*5 P 23; 23.5,69,71 

TTY: (edit command) ............................. 9.66,70-72; 15.21 

TTY: (typed by editor) 9.71 

type numbers 10.15 

TYPEP[X;N] 10.16 

TYPERECORD (record package) 23.54-55 

typescript files 21.30 

TYPE-AHEAD (prog. asst. command) 22.28-29 

TYPE? (record package) ... ................... 23.53-54 

U (value of ARGLIST) 8.6 

UB (break command) 15.8 

UCASELST (prettydef variable/parameter) 14.62 

UNADVISE[X] ML* 19.6,8-9 

UNADVISED (typed by system) 15.25 

UMARYOP (property name) 23.73 

UNBLOCK (edit command) . 9.79 

unbound atom 16.1; 17.15-19 

unboxed numbers 13.13 

unboxed numbers (in arrays) 3.9; 10.13 

unboxing . 13.1,3, 13 

UNBREAK[X] ML* 15.19,23-24; 21.6 

(UNBREAKABLE) 15.22 

UNBREAKINCFN] 15.24 

UNBREAK0[ FN ; TAIL] 15.23-24 

UNBROKEN (typed by advise) 19.6 
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UNBROKEN (typed by compiler) 18.7 

UNBROKEN (typed by system) . .. 15.25 

undefined function . ... 16.1; 17.15-19 

UNDEFINED OR ILLEGAL GO (error message) . 5.7; 16.8 

(UNDEFINED TAG) (compiler error message) 5.7; 18.51 

(UNDEFINED TAG, ASSEMBLE) (compiler error message) 18.51 

(UNDEFINED TAG, LAP) (compiler error message) ... 18.51 

UNDEFINED USER INTERRUPT (error message) 16.17 

UNDO (edit command) 9.10,78; 22.61 

UNDO (prog. asst. command) . . 17.4; 22.14,22-23,43,59, 

. . . 61 

undoing . . . . 22.5,38-43,55-60,62 

undoing DWIM corrections 22.23; 23.67 

undoing out of order . ... 22.23,42 

undoing (in editor) 9.10,36,78-79; 22.62 

UNDOLISPX[LINE] . 22.59 

UNDOLISPXl[ EVENT ; FLG ; DWIMCHANGES] 22.59 

UNDOLST (editor variable/parameter) 9.72,78-79,84; 22.62 

UNDONE (typed by editor) 9.78 

UNDONE (typed by system) . 22.23,59 

UNDONLSETQC UNDOFORM ;UHD0FN] ML 22.59-60 

UNDOSAVE[ UNDOFORM ;HiSTENTRY] 22.45-46,56 

UNFIND (editor variable/parameter) . 9. 25, 35, 41 -42 , 46, 48-51 , 

. . . ... ,. 72-73,76,84 

UNION[X;Y] .......... . . 6.10 

UNLESS (clisp iterative statement operator) 23.22 

UNPACK[ X ; FLG ;RDTBL] SUBR 10.3 

unreading , 22.10-11,18,51 

UNSAVED (typed by dwim) . . 17.17-18 

UNSAVED (typed by editor) 9.85 

UNSAVEDEF[ X; TYP] 8.8; 17.17-18 

UNSET[ NAME ] ..... . , 22,43,56 

UNTIL (clisp iterative statement operator) 23.22 

UNUSUAL CDR ARG LIST (error message) 16.10 

UP (edit command) 9.12,15-16,25,43 

UPDATEF ILESt PRLST ;FLST ] 14 .65 , 75 

UPFINDFLG (editor variable/parameter) 9.25,28,44 

USE (prog. asst. command) 22.15-16,18,22 

(USED AS ARG TO NUMBER FN?) 

(compiler error messagie) 18.52 

(USED BLK APPLY WHEN NOT APPLICABLE) 

(compiler error message) 18.52 

USEMAPFLG ( system variable/parameter ) 14.44 

USER BREAK (error message) ,. 16.12 

user data types . . . . . 10 . 16 ; 23 . 53 , 56 

user interrupt characters 2.5; 16.16 

USEREXEC[LISPXID;LISPXXMACROS;LISPXXUSERFN] . 22.49 

USERMACROS (editor variable/parameter) 9.70; 14.51 

USERMACROS (prettydef command) 9.70,80; 14.51 

USERNAMEX A] ... ....... .................... ....... 21.23 

USERNAME (prog. asst. variable/parameter) ....... 22.65 

USERNAME (system variable /parameter ) .. ...... 21.23 

USERNAME LST (prog, asst . variable/parameter ) .... 22.66 

USERNUMBER[ A] 21.23 

USERRECLST (record package) . . 23.61 

USERSYMS (edita command/parameter) 21.14-15 

USERWORDS (dwim variable/parameter) 17.13-14,24,28-29 
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USERWORDS (system variable/parameter) 9.86-88 

USE-ARCS (property name) 22.45 

USING (record package) 23.60 

U~CAS£[X] , 9.74; 14.62 

U.B.A. breaks .. 15.10 

U.B.A. (error message) 2.9; 16.1,4; 17.15 

U.D.F. breaks 15.11 

U.D.F. T FIX? (typed by dwim) 17.8 

U.D.F. T (typed by dwim) 17.8 

U.D.F. (error message) 16.1-2,4; 17.2,15 

VAG[X] 5UBR 13.13-14 

value cell 2.3; 5.1,9; 12.1, 

16.1 

value of a break • 15.6; 16.2 

value of a property 7.1 

VALUE (property name) 5.9; 22.43,55-56 

VALUEOF[X] ML* . 21.21; 22.33,46,54 

variable bindings 2.9; 11.5-7; 12.1-7 

VARIABLES[POS] 12.9; 15.10 

VARPRINT[ DONELST ; TREE LSI] . 20.8 

VARS[ FN ; EXPRFLG] ... 14.40; 20.9 

VARS (prettydef command) .......... 14.50 

version numbers . . . . . . . .... ... . ... ..... . . ........ 14 . 2 

yiRGIMF.N[ FN ; FLG ] .'v. ,y...:. . 15.25 

WHEN ( clisp iterative statement operator) 23.22 

WHERE (clisp iterative statement operator) 23.31 

WHEREIS[X;TYPE;FILES] 14.73 

WHILE (clisp iterative statement operator) 23.22 

WIDEPAPER[ FLG ] 14.57 

WITH (in REPLACE command) (in editor) ........... 9.42 

WITH (in SURROUND command) (in editor) 9.48 

WORLD (as argument to RELINK) 18.27 

WRITEFILE[X;FILE] 14.44 

(XTR . (?) (edit command) 9.45 

YESFNS ( printstructure variable/parameter) 20 .3 

ZEROP[X] 13.4 

C ♦ . 3.2 

[,] (inserted by prettyprint) 14.55 

- (clisp operator ) . . 23 . 14 

~ (in pattern match compiler) 23.42 

> (carriage-return) 2.5; 14.17-18 

! (in pattern match compiler) 23.43-45 

! (use with <,> in clisp) 23.16 

!E (edit command) 22.31 ,61 

IE (prog. asst. command) 22.31 

! EVAL (break command) 15.7 

!F (edit command) 22.31,61 

IF (prog. asst. command) 22.31 

!GO (break command) ., 15.7,17 

!N (edit command) , . . . 22.31,61 

IN (prog. asst. command) 22.31 

! NX ( edit command) , 9. 19-20 

! OK (break command) 15.7,17 

IUNDO (edit command) 9.78 

! VALUE (break variable/parameter) 15.7,17 

! VALUE (with advising) 19.2,4 

! I (use with <,> in clisp) 23.16 
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!0 (edit command) . . 

"<c.r .>" (use 1n history commands) 

f (followed by a number) 

#CAREFULCOLUMNS ( prettydef variable/parameter) . . 
#n (n a number, 1n pattern match compiler) ...... 

*RPARS (prettydef variable/parameter) 

#SPELLIMGS1 (dwim variable/parameter) 

#SPELLINGS2 (dwim variable/parameter) 

#SPELLINGS3 (dwim variable/parameter) 

#UNDOSAVES (prog. asst. variable/parameter) ..... 

#USERWORDS (dwim variable/parameter) 

##[COMS] ML" . . 

«*# ( 1n INSERT , REPLACE, and CHANGE commands) 

##■ (typed by system) . . 

5 (alt-mode) .. 

S (alt-mode) (in clisp) 

S ( alt-mode ) ( in edit pattern) 

S (alt-mode) (in spelling correction) 
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